"""Calibrex command-line entry point."""

from __future__ import annotations

import argparse
import dataclasses
import json
import shlex
import shutil
import sys
from collections.abc import Callable, Iterator
from pathlib import Path
from typing import TYPE_CHECKING, Any, Literal, NoReturn, TypeVar, cast

from calibrex import __version__
from calibrex.cli.help import (
    CHECK_ADVANCED_TITLE,
    CHECK_ARGUMENT_GROUPS,
    HELP_EPILOG,
    CalibrexArgumentParser,
    GroupedHelpFormatter,
    group_arguments,
)
from calibrex.core.exceptions import BenchmarkError, CalibrexError

if TYPE_CHECKING:
    from calibrex.core.capture_manifest import SensorIdentity
    from calibrex.core.config import CalibrationConfig
    from calibrex.core.evidence_bundle import EvidenceBundleVerification
    from calibrex.core.result import CalibrationResult
    from calibrex.data.inspect import DatasetInspection
    from calibrex.evaluation.compare import ComparisonSide, ResultComparison
    from calibrex.evaluation.report_compare import ReportComparison
    from calibrex.export.autoware_promotion import AutowarePromotionPolicy
    from calibrex.export.autoware_smoke import AutowareSmokeCommand


_Setting = TypeVar("_Setting")


def _loaded_setting(module_name: str, name: str, fallback: _Setting) -> _Setting:
    # Preserve explicit overrides on an already loaded public module without
    # importing a calibration pipeline merely to construct parser defaults.
    module = sys.modules.get(module_name)
    return fallback if module is None else cast(_Setting, getattr(module, name, fallback))


class _SchemaChoices:
    """Resolve schema metadata only when parsing or displaying these choices."""

    def __init__(self, *, validation: bool) -> None:
        self._validation = validation
        self._choices: tuple[str, ...] | None = None

    def _values(self) -> tuple[str, ...]:
        if self._choices is None:
            from calibrex.core.schema_registry import schema_kinds, validatable_kinds

            self._choices = (
                ("auto", *validatable_kinds())
                if self._validation
                else (*schema_kinds(), "ledger", "all")
            )
        return self._choices

    def __iter__(self) -> Iterator[str]:
        return iter(self._values())

    def __contains__(self, value: object) -> bool:
        return value in self._values()


def main(argv: list[str] | None = None) -> int:
    """Run the Calibrex CLI."""

    parser = _build_parser()
    args = parser.parse_args(argv)
    args.invoked_argv = list(sys.argv[1:] if argv is None else argv)
    command = cast(Callable[[argparse.Namespace], int], args.func)
    try:
        return command(args)
    except CalibrexError as exc:
        print(f"calibrex: error: {exc}", file=sys.stderr)
        return 2


def _positive_float(value: str) -> float:
    """Parse an argparse value as a positive finite number."""

    try:
        number = float(value)
    except ValueError as exc:
        msg = f"invalid positive number: {value!r}"
        raise argparse.ArgumentTypeError(msg) from exc
    if not number > 0.0 or number == float("inf"):
        msg = f"expected a positive number, got {value!r}"
        raise argparse.ArgumentTypeError(msg)
    return number


def _camera_lidar_far_control_t(value: str) -> float:
    """Parse a finite adoption margin that cannot weaken the ordinary control."""

    from calibrex.core.camera_lidar_edge import DEFAULT_MIN_CONTROL_T

    number = _positive_float(value)
    if number < DEFAULT_MIN_CONTROL_T:
        raise argparse.ArgumentTypeError(f"must be at least {DEFAULT_MIN_CONTROL_T:g}")
    return number


def _positive_int(value: str) -> int:
    """Parse an argparse value as a positive (>= 1) integer."""

    try:
        number = int(value)
    except ValueError as exc:
        msg = f"invalid positive integer: {value!r}"
        raise argparse.ArgumentTypeError(msg) from exc
    if number < 1:
        msg = f"must be >= 1, got {number}"
        raise argparse.ArgumentTypeError(msg)
    return number


def _holdout_ratio(value: str) -> float:
    """Parse an argparse value as a holdout ratio in (0.0, 0.9].

    The upper bound matches `calibrex.evaluation.holdout.split_indices`;
    a ratio of 0.0 is rejected because it would leave every online batch
    without holdout evidence, so no batch could ever be accepted.
    """

    try:
        ratio = float(value)
    except ValueError as exc:
        msg = f"invalid holdout ratio: {value!r}"
        raise argparse.ArgumentTypeError(msg) from exc
    if not 0.0 < ratio <= 0.9:
        msg = f"must be > 0.0 and <= 0.9, got {ratio}"
        raise argparse.ArgumentTypeError(msg)
    return ratio


def _packaged_kitti_lidar_camera_demo_config() -> Path:
    return (
        Path(__file__).resolve().parents[1]
        / "resources"
        / "kitti_lidar_camera_evidence"
        / "config.yaml"
    )


def _coverage_ratio(value: str) -> float:
    """Parse an argparse value as a coverage target in (0, 1)."""

    try:
        ratio = float(value)
    except ValueError as exc:
        msg = f"invalid coverage ratio: {value!r}"
        raise argparse.ArgumentTypeError(msg) from exc
    if not 0.0 < ratio < 1.0:
        msg = f"must be > 0.0 and < 1.0, got {ratio}"
        raise argparse.ArgumentTypeError(msg)
    return ratio


def _fit_ratio(value: str) -> float:
    """Parse an argparse value as a block fit ratio in (0, 1)."""

    try:
        ratio = float(value)
    except ValueError as exc:
        msg = f"invalid fit block ratio: {value!r}"
        raise argparse.ArgumentTypeError(msg) from exc
    if not 0.0 < ratio < 1.0:
        msg = f"must be > 0.0 and < 1.0, got {ratio}"
        raise argparse.ArgumentTypeError(msg)
    return ratio


def _overconfidence_scale(value: str) -> float:
    """Parse an argparse value as an overconfidence control scale in (0, 1)."""

    try:
        scale = float(value)
    except ValueError as exc:
        msg = f"invalid overconfidence scale: {value!r}"
        raise argparse.ArgumentTypeError(msg) from exc
    if not 0.0 < scale < 1.0:
        msg = f"must be > 0.0 and < 1.0, got {scale}"
        raise argparse.ArgumentTypeError(msg)
    return scale


def _build_parser() -> argparse.ArgumentParser:
    from calibrex.data.livox_profile_fields import LIVOX_PROFILE_FIELDS
    from calibrex.evaluation.camera_lidar_defaults import (
        DEFAULT_CONFIDENCE_THRESHOLDS,
        DEFAULT_INITIALIZER_CONFIDENCE_THRESHOLDS,
        DEFAULT_INITIALIZER_RANDOM_SEEDS,
        DEFAULT_INITIALIZER_RANSAC_THRESHOLDS_PX,
    )

    profile_choices = sorted(
        getattr(sys.modules.get("calibrex.data.livox_ros2"), "LIVOX_PROFILES", LIVOX_PROFILE_FIELDS)
    )
    confidence_thresholds = _loaded_setting(
        "calibrex.evaluation.camera_lidar_confidence_calibration",
        "DEFAULT_CONFIDENCE_THRESHOLDS",
        DEFAULT_CONFIDENCE_THRESHOLDS,
    )
    initializer_module = "calibrex.evaluation.camera_lidar_initializer_calibration"
    initializer_confidence = _loaded_setting(
        initializer_module,
        "DEFAULT_INITIALIZER_CONFIDENCE_THRESHOLDS",
        DEFAULT_INITIALIZER_CONFIDENCE_THRESHOLDS,
    )
    initializer_ransac = _loaded_setting(
        initializer_module,
        "DEFAULT_INITIALIZER_RANSAC_THRESHOLDS_PX",
        DEFAULT_INITIALIZER_RANSAC_THRESHOLDS_PX,
    )
    initializer_seeds = _loaded_setting(
        initializer_module, "DEFAULT_INITIALIZER_RANDOM_SEEDS", DEFAULT_INITIALIZER_RANDOM_SEEDS
    )

    parser = CalibrexArgumentParser(
        prog="calibrex", formatter_class=GroupedHelpFormatter, epilog=HELP_EPILOG
    )
    parser.add_argument("--version", action="version", version=f"Calibrex {__version__}")
    subcommands = parser.add_subparsers(dest="command", required=True, metavar="<command>")

    doctor = subcommands.add_parser(
        "doctor",
        help="check the environment and optionally diagnose a dataset",
    )
    doctor.add_argument("path", type=Path, nargs="?")
    doctor.add_argument(
        "--workflow",
        choices=["environment", "koide"],
        default="environment",
        help="run the standard environment doctor or the Koide input preflight",
    )
    doctor.add_argument(
        "--config",
        type=Path,
        help="CalibrationConfig used by --workflow koide",
    )
    doctor.add_argument(
        "--type",
        choices=[
            "auto",
            "a2d2-lidar",
            "a2d2_lidar",
            "filesystem",
            "kitti-raw",
            "kitti_raw",
            "livox-pcd",
            "livox_pcd",
            "mcap",
            "nuscenes",
            "rosbag1",
            "rosbag2",
            "tum-rgbd",
            "tum_rgbd",
        ],
        default="auto",
        help="dataset type; defaults to path-based inference",
    )
    doctor.add_argument("--sample-limit", type=_positive_int)
    doctor.add_argument("--output", type=Path, help="write a doctor YAML/JSON artifact")
    doctor.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    doctor.set_defaults(func=_cmd_doctor)

    schema = subcommands.add_parser("schema", help="print JSON schema")
    schema_kind = schema.add_argument(
        "kind",
        help="artifact kind, 'ledger' for the schema version ledger, or 'all'",
    )
    # Assign after add_argument's eager metavar check; argparse resolves this
    # container normally for the selected command's parsing and help output.
    schema_kind.choices = _SchemaChoices(validation=False)
    schema.add_argument("--output", type=Path, help="write schema to a file")
    schema.add_argument("--output-dir", type=Path, help="write all schemas to a directory")
    schema.set_defaults(func=_cmd_schema)

    validate = subcommands.add_parser("validate", help="validate a Calibrex artifact")
    validate.add_argument("path", type=Path)
    validation_kind = validate.add_argument(
        "--kind",
        default="auto",
        help="artifact kind; defaults to schema_version auto-detection",
    )
    validation_kind.choices = _SchemaChoices(validation=True)
    validate.add_argument(
        "--verify-inputs",
        action="store_true",
        help=(
            "for capture-manifest, recompute source/config paths as well as the "
            "portable self-digest; relocated/missing inputs fail"
        ),
    )
    validate.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    validate.set_defaults(func=_cmd_validate)

    benchmark = subcommands.add_parser(
        "benchmark",
        help="aggregate a shared N-way trial matrix",
    )
    benchmark.add_argument("definition", type=Path)
    benchmark.add_argument("--output", type=Path, required=True)
    benchmark.add_argument("--markdown-output", type=Path)
    benchmark.add_argument(
        "--update-markdown",
        action="append",
        type=Path,
        default=[],
        help="replace the matching marker-delimited table; may be repeated",
    )
    benchmark.add_argument("--json", action="store_true", help="emit machine-readable summary")
    benchmark.set_defaults(func=_cmd_benchmark)

    calibration_ci = subcommands.add_parser(
        "ci",
        help="validate and assess a calibration result for continuous integration",
    )
    calibration_ci.add_argument("candidate", type=Path)
    calibration_ci.add_argument("--baseline", type=Path)
    calibration_ci.add_argument("--policy", type=Path)
    calibration_ci.add_argument(
        "--output-dir",
        type=Path,
        default=Path("calibrex-ci"),
    )
    calibration_ci.add_argument(
        "--allow-incompatible-protocol",
        action="store_true",
        help="report protocol incompatibility without failing the CI decision",
    )
    calibration_ci.add_argument(
        "--enforce",
        action="store_true",
        help="return non-zero unless the final CI status is pass",
    )
    calibration_ci.add_argument("--json", action="store_true")
    calibration_ci.set_defaults(func=_cmd_calibration_ci)

    replay = subcommands.add_parser(
        "replay",
        help="digest-bound raw-capture calibration replay and field-replacement pilot",
    )
    replay_subcommands = replay.add_subparsers(dest="replay_command", required=True)
    replay_plan = replay_subcommands.add_parser(
        "plan", help="verify inputs and write a read-only replay plan"
    )
    replay_plan.add_argument("definition", type=Path)
    replay_plan.add_argument("--output", type=Path, required=True)
    replay_plan.add_argument("--json", action="store_true")
    replay_plan.set_defaults(func=_cmd_replay_plan)
    replay_run = replay_subcommands.add_parser("run", help="execute or import a replay candidate")
    replay_run.add_argument("definition", type=Path)
    replay_run.add_argument("--output-dir", type=Path, required=True)
    replay_run.add_argument(
        "--field-replacement",
        action="store_true",
        help="also record vehicle/sensor lifecycle pilot",
    )
    replay_run.add_argument("--json", action="store_true")
    replay_run.set_defaults(func=_cmd_replay_run)
    replay_verify = replay_subcommands.add_parser(
        "verify", help="verify a replay result and every stage digest"
    )
    replay_verify.add_argument("result", type=Path)
    replay_verify.add_argument("--definition", type=Path)
    replay_verify.add_argument("--json", action="store_true")
    replay_verify.set_defaults(func=_cmd_replay_verify)
    replay_compare = replay_subcommands.add_parser("compare", help="compare two replay results")
    replay_compare.add_argument("left", type=Path)
    replay_compare.add_argument("right", type=Path)
    replay_compare.add_argument("--output", type=Path, required=True)
    replay_compare.add_argument("--json", action="store_true")
    replay_compare.set_defaults(func=_cmd_replay_compare)
    replay_pilot = replay_subcommands.add_parser(
        "field-replacement", help="run a sensor replacement lifecycle pilot"
    )
    replay_pilot.add_argument("definition", type=Path)
    replay_pilot.add_argument("--output-dir", type=Path, required=True)
    replay_pilot.add_argument("--json", action="store_true")
    replay_pilot.set_defaults(func=_cmd_replay_field_replacement)

    multi_lidar_service = subcommands.add_parser(
        "multi-lidar-service",
        help="digest-bound, read-only multi-LiDAR replacement planning and evaluation",
    )
    multi_lidar_service_subcommands = multi_lidar_service.add_subparsers(
        dest="multi_lidar_service_command", required=True
    )
    multi_lidar_plan = multi_lidar_service_subcommands.add_parser(
        "plan", help="verify inputs and write a read-only replacement plan"
    )
    multi_lidar_plan.add_argument("definition", type=Path)
    multi_lidar_plan.add_argument("--output", type=Path, required=True)
    multi_lidar_plan.add_argument("--json", action="store_true")
    multi_lidar_plan.set_defaults(func=_cmd_multi_lidar_service_plan)

    multi_lidar_evaluate = multi_lidar_service_subcommands.add_parser(
        "evaluate", help="evaluate replay gates, edge scope, and graph topology"
    )
    multi_lidar_evaluate.add_argument("plan", type=Path)
    multi_lidar_evaluate.add_argument(
        "--candidate-replay",
        type=Path,
        help="candidate raw-replay result (defaults to the plan reference)",
    )
    multi_lidar_evaluate.add_argument("--output", type=Path, required=True)
    multi_lidar_evaluate.add_argument("--evaluation-id")
    multi_lidar_evaluate.add_argument("--json", action="store_true")
    multi_lidar_evaluate.set_defaults(func=_cmd_multi_lidar_service_evaluate)

    multi_lidar_verify = multi_lidar_service_subcommands.add_parser(
        "verify", help="verify a plan or evaluation and all available source digests"
    )
    multi_lidar_verify.add_argument("artifact", type=Path)
    multi_lidar_verify.add_argument(
        "--plan", type=Path, help="plan to bind when verifying an evaluation"
    )
    multi_lidar_verify.add_argument("--json", action="store_true")
    multi_lidar_verify.set_defaults(func=_cmd_multi_lidar_service_verify)

    camera_imu_service = subcommands.add_parser(
        "camera-imu-service",
        help="digest-bound, read-only camera--IMU replacement planning and evaluation",
    )
    camera_imu_service_subcommands = camera_imu_service.add_subparsers(
        dest="camera_imu_service_command", required=True
    )
    camera_imu_plan = camera_imu_service_subcommands.add_parser(
        "plan", help="verify inputs and write a read-only replacement plan"
    )
    camera_imu_plan.add_argument("definition", type=Path)
    camera_imu_plan.add_argument("--output", type=Path, required=True)
    camera_imu_plan.add_argument("--json", action="store_true")
    camera_imu_plan.set_defaults(func=_cmd_camera_imu_service_plan)

    camera_imu_evaluate = camera_imu_service_subcommands.add_parser(
        "evaluate", help="evaluate replay, evidence, metric, and component gates"
    )
    camera_imu_evaluate.add_argument("plan", type=Path)
    camera_imu_evaluate.add_argument(
        "--candidate-replay",
        type=Path,
        help="candidate raw-replay result (defaults to the plan reference)",
    )
    camera_imu_evaluate.add_argument("--output", type=Path, required=True)
    camera_imu_evaluate.add_argument("--evaluation-id")
    camera_imu_evaluate.add_argument("--json", action="store_true")
    camera_imu_evaluate.set_defaults(func=_cmd_camera_imu_service_evaluate)

    camera_imu_verify = camera_imu_service_subcommands.add_parser(
        "verify", help="verify a plan or evaluation and all source digests"
    )
    camera_imu_verify.add_argument("artifact", type=Path)
    camera_imu_verify.add_argument(
        "--plan", type=Path, help="plan to bind when verifying an evaluation"
    )
    camera_imu_verify.add_argument("--json", action="store_true")
    camera_imu_verify.set_defaults(func=_cmd_camera_imu_service_verify)

    radar_service = subcommands.add_parser(
        "radar-service",
        help="digest-bound, read-only automotive radar replacement planning and evaluation",
    )
    radar_service_subcommands = radar_service.add_subparsers(
        dest="radar_service_command", required=True
    )
    radar_plan = radar_service_subcommands.add_parser(
        "plan", help="verify inputs and write a read-only radar replacement plan"
    )
    radar_plan.add_argument("definition", type=Path)
    radar_plan.add_argument("--output", type=Path, required=True)
    radar_plan.add_argument("--json", action="store_true")
    radar_plan.set_defaults(func=_cmd_radar_service_plan)

    radar_evaluate = radar_service_subcommands.add_parser(
        "evaluate", help="evaluate replay, evidence, metric, and component gates"
    )
    radar_evaluate.add_argument("plan", type=Path)
    radar_evaluate.add_argument(
        "--candidate-replay",
        type=Path,
        help="candidate raw-replay result (defaults to the plan reference)",
    )
    radar_evaluate.add_argument("--output", type=Path, required=True)
    radar_evaluate.add_argument("--evaluation-id")
    radar_evaluate.add_argument("--json", action="store_true")
    radar_evaluate.set_defaults(func=_cmd_radar_service_evaluate)

    radar_verify = radar_service_subcommands.add_parser(
        "verify", help="verify a radar plan or evaluation and all source digests"
    )
    radar_verify.add_argument("artifact", type=Path)
    radar_verify.add_argument("--plan", type=Path, help="plan to bind when verifying an evaluation")
    radar_verify.add_argument("--json", action="store_true")
    radar_verify.set_defaults(func=_cmd_radar_service_verify)

    verify = subcommands.add_parser(
        "verify",
        help="verify an evidence bundle manifest or saved verification artifact",
    )
    verify.add_argument("artifact", type=Path)
    verify.add_argument("--output", type=Path, help="write verification YAML/JSON")
    verify.add_argument(
        "--require-raw-recomputed",
        action="store_true",
        help=(
            "fail unless primary evidence is recomputed from verified raw inputs "
            "with SHA-backed input files"
        ),
    )
    verify.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    verify.set_defaults(func=_cmd_verify)

    assess = subcommands.add_parser("assess", help="apply a policy to evidence")
    assess.add_argument("evidence", type=Path, help="report evidence artifact")
    assess.add_argument(
        "--policy",
        type=Path,
        help="policy artifact to apply; defaults to the built-in falsification policy",
    )
    assess.add_argument("--output", type=Path, help="write assessment YAML/JSON")
    assess.add_argument(
        "--enforce",
        action="store_true",
        help="return non-zero when the assessment status is not pass",
    )
    assess.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    assess.set_defaults(func=_cmd_assess)

    evidence = subcommands.add_parser(
        "evidence",
        help="materialize evidence.json from an existing result without recomputing metrics",
    )
    evidence.add_argument("result", type=Path)
    evidence.add_argument("--output", type=Path, required=True)
    evidence.add_argument(
        "--sidecars-dir",
        type=Path,
        help=(
            "also write assessment/protocol/policy/transforms/bundle/verification "
            "sidecars into this directory"
        ),
    )
    evidence.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    evidence.set_defaults(func=_cmd_evidence)

    init = subcommands.add_parser("init", help="write a starter config")
    init.add_argument(
        "profile",
        nargs="?",
        choices=["camera-lidar-imu", "autonomous-driving-rig"],
        help="legacy synthetic starter profile (ignored when --template is set)",
    )
    init.add_argument("--output", type=Path, help="output config file or directory")
    init.add_argument(
        "--template",
        help=("copy a working sensor template config (for example velodyne_vlp16_pair_rosbag2)"),
    )
    init.add_argument(
        "--list-templates",
        action="store_true",
        help="list available sensor templates and exit",
    )
    init.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    init.set_defaults(func=_cmd_init)

    calibrate = subcommands.add_parser("calibrate", help="run calibration")
    calibrate.add_argument("config", type=Path)
    calibrate.add_argument(
        "--dry-run",
        action="store_true",
        help="validate without writing results",
    )
    calibrate.add_argument("--output-dir", type=Path)
    calibrate.add_argument(
        "--candidate-extrinsics",
        type=Path,
        action="append",
        default=[],
        help="load candidate extrinsics from a YAML/JSON file; may be repeated",
    )
    calibrate.add_argument("--strict", action="store_true", help="treat warnings as failures")
    calibrate.add_argument("--seed", type=int)
    calibrate.add_argument(
        "--online",
        action="store_true",
        help=(
            "run an online/streaming calibration session instead of one offline solve; "
            "replays the dataset's LiDAR frames as an ordered point stream, warm-starting "
            "the native point-to-plane solve per batch and gating each batch with a "
            "holdout check (see --batch-size, --rolling-window, --holdout-ratio)"
        ),
    )
    calibrate.add_argument(
        "--batch-size",
        type=_positive_int,
        default=500,
        help="online mode: number of target LiDAR points replayed per batch",
    )
    calibrate.add_argument(
        "--rolling-window",
        type=_positive_int,
        default=2000,
        help="online mode: number of recent holdout residuals kept in the rolling RMSE window",
    )
    calibrate.add_argument(
        "--holdout-ratio",
        type=_holdout_ratio,
        default=0.2,
        help=(
            "online mode: fraction of each batch held out for the per-batch gate; "
            "must be > 0.0 and <= 0.9"
        ),
    )
    calibrate.add_argument(
        "--accumulation-batches",
        type=_positive_int,
        default=1,
        help=(
            "online mode: number of accepted batches whose train points are retained "
            "for observability and solve (1 preserves per-batch behavior)"
        ),
    )
    calibrate.add_argument(
        "--max-accumulated-train-points",
        type=_positive_int,
        default=None,
        help=(
            "online mode: optional cap on retained train points when accumulating "
            "observations across batches"
        ),
    )
    calibrate.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    calibrate.set_defaults(func=_cmd_calibrate)

    compile_cmd = subcommands.add_parser("compile", help="compile config to a graph problem")
    compile_cmd.add_argument("config", type=Path)
    compile_cmd.add_argument("--output", type=Path, help="write compiled problem YAML/JSON")
    compile_cmd.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    compile_cmd.set_defaults(func=_cmd_compile)

    evaluate = subcommands.add_parser("evaluate", help="evaluate a result file")
    evaluate.add_argument("result", type=Path)
    evaluate.add_argument("--output-dir", type=Path)
    evaluate.add_argument("--strict", action="store_true")
    evaluate.add_argument(
        "--threshold-profile",
        choices=["default", "autonomous_driving"],
        help="override metric threshold profile",
    )
    evaluate.add_argument("--export-html", action="store_true", help="write report.html")
    evaluate.add_argument("--json", action="store_true")
    evaluate.set_defaults(func=_cmd_evaluate)

    render = subcommands.add_parser(
        "render",
        help="render artifacts from an existing result without recomputing metrics",
    )
    render.add_argument("result", type=Path)
    render.add_argument(
        "--format",
        choices=["html", "evidence-card"],
        default="html",
        help="rendered artifact format",
    )
    render.add_argument("--output-dir", type=Path)
    render.add_argument("--html", type=Path, help="HTML report path or filename")
    render.add_argument("--output", type=Path, help="evidence-card SVG path or filename")
    render.add_argument("--json", action="store_true")
    render.set_defaults(func=_cmd_render)

    report = subcommands.add_parser(
        "report",
        help="deprecated alias for 'render --format html'",
    )
    report.add_argument("result", type=Path)
    report.add_argument("--output-dir", type=Path)
    report.add_argument("--html", type=Path, help="HTML report path or filename")
    report.add_argument("--json", action="store_true")
    report.set_defaults(func=_cmd_report)

    compare = subcommands.add_parser("compare", help="compare two result files")
    compare.add_argument("left_result", type=Path)
    compare.add_argument("right_result", type=Path)
    compare.add_argument(
        "--format",
        choices=["data", "evidence-table"],
        default="data",
        help="machine-readable comparison data or a provenance-bound SVG table",
    )
    compare.add_argument("--output", type=Path, help="write comparison data or SVG")
    compare.add_argument("--left-label", default="baseline", help="left SVG column label")
    compare.add_argument("--right-label", default="candidate", help="right SVG column label")
    compare.add_argument(
        "--enforce-compatible",
        action="store_true",
        help="return non-zero unless evidence protocols are compatible",
    )
    compare.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    compare.set_defaults(func=_cmd_compare)

    report_compare = subcommands.add_parser(
        "report-compare",
        help="compare two or more labeled result files in one report artifact",
    )
    report_compare.add_argument(
        "entries",
        nargs="+",
        metavar="LABEL=RESULT",
        help="labeled result file, e.g. reference=dataset_result.yaml",
    )
    report_compare.add_argument(
        "--reference",
        metavar="LABEL",
        help="compare this entry against each other entry instead of all pairs",
    )
    report_compare.add_argument("--output", type=Path, help="write report comparison as YAML/JSON")
    report_compare.add_argument(
        "--enforce-compatible",
        action="store_true",
        help="return non-zero unless every compared pair has compatible evidence protocols",
    )
    report_compare.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    report_compare.set_defaults(func=_cmd_report_compare)

    window_consistency = subcommands.add_parser(
        "window-consistency",
        help="gate one transform across multiple labeled capture-window results",
    )
    window_consistency.add_argument(
        "entries",
        nargs="+",
        metavar="LABEL=RESULT",
        help="labeled result file, e.g. main=dynamic_result.yaml",
    )
    window_consistency.add_argument("--transform", required=True, help="transform id to compare")
    window_consistency.add_argument(
        "--max-translation-delta-m",
        type=float,
        required=True,
        help="maximum allowed pairwise translation delta in metres",
    )
    window_consistency.add_argument(
        "--max-rotation-delta-deg",
        type=float,
        required=True,
        help="maximum allowed pairwise rotation delta in degrees",
    )
    window_consistency.add_argument("--reference", metavar="LABEL")
    window_consistency.add_argument("--output", type=Path, help="write the consistency artifact")
    window_consistency.add_argument(
        "--enforce",
        action="store_true",
        help="return non-zero when the consistency grade is not PASS",
    )
    window_consistency.add_argument(
        "--json", action="store_true", help="emit machine-readable JSON"
    )
    window_consistency.set_defaults(func=_cmd_window_consistency)

    trajectory_window_drift = subcommands.add_parser(
        "trajectory-window-drift",
        help="recompute odometry/map consistency for each configured capture window",
    )
    trajectory_window_drift.add_argument("config", type=Path)
    trajectory_window_drift.add_argument(
        "--reference-result",
        type=Path,
        help="optional completed result to bind into artifact provenance",
    )
    trajectory_window_drift.add_argument(
        "--deskew",
        choices=["config", "on", "off"],
        default="config",
        help="override use_point_time_offsets for this diagnostic",
    )
    trajectory_window_drift.add_argument(
        "--odometry-burst-policy",
        choices=["config", "preserve", "keep_first", "keep_last"],
        default="config",
        help="override odometry burst preprocessing for this diagnostic",
    )
    trajectory_window_drift.add_argument(
        "--odometry-burst-min-interval-s",
        type=float,
        help="override the minimum retained odometry sample interval",
    )
    trajectory_window_drift.add_argument(
        "--output", type=Path, required=True, help="write the drift artifact"
    )
    trajectory_window_drift.add_argument(
        "--json", action="store_true", help="emit machine-readable JSON"
    )
    trajectory_window_drift.set_defaults(func=_cmd_trajectory_window_drift)

    capture_readiness = subcommands.add_parser(
        "calibration-readiness",
        help="check motion and geometry readiness before LiDAR calibration",
    )
    capture_readiness.add_argument("config", type=Path)
    capture_readiness.add_argument(
        "--output", type=Path, required=True, help="write the readiness artifact"
    )
    capture_readiness.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    capture_readiness.add_argument(
        "--enforce",
        action="store_true",
        help="return non-zero unless every window passes readiness",
    )
    capture_readiness.set_defaults(func=_cmd_capture_readiness)

    continuous_time_lidar = subcommands.add_parser(
        "continuous-time-lidar-pair",
        help="jointly profile LiDAR extrinsic and clock offset on rosbag1/rosbag2",
    )
    continuous_time_lidar.add_argument("config", type=Path)
    continuous_time_lidar.add_argument(
        "--output", type=Path, required=True, help="write the continuous-time artifact"
    )
    continuous_time_lidar.add_argument(
        "--json", action="store_true", help="emit machine-readable JSON"
    )
    continuous_time_lidar.add_argument(
        "--enforce",
        action="store_true",
        help="return non-zero unless optimization, rank, and holdout evidence pass",
    )
    continuous_time_lidar.set_defaults(func=_cmd_continuous_time_lidar_pair)

    metrics = subcommands.add_parser("metrics", help="list registered metric definitions")
    metrics.add_argument("--json", action="store_true")
    metrics.set_defaults(func=_cmd_metrics)

    public = subcommands.add_parser("public-datasets", help="inspect public dataset catalog")
    public_subcommands = public.add_subparsers(dest="public_command", required=True)
    public_list = public_subcommands.add_parser("list", help="list public datasets")
    public_list.add_argument("--json", action="store_true")
    public_list.set_defaults(func=_cmd_public_datasets_list)
    public_show = public_subcommands.add_parser("show", help="show one public dataset")
    public_show.add_argument("dataset")
    public_show.add_argument("--json", action="store_true")
    public_show.set_defaults(func=_cmd_public_datasets_show)

    demo = subcommands.add_parser("demo", help="run reproducible public demos")
    demo_subcommands = demo.add_subparsers(dest="demo_command", required=True)
    livox_demo = demo_subcommands.add_parser(
        "livox-evidence",
        help="download public Livox PCD data and recompute evidence artifacts",
    )
    livox_demo.add_argument(
        "--config",
        type=Path,
        default=Path("examples/public_datasets/livox_horizon_horizon_pcd_sample/config.yaml"),
        help="base Livox evidence config",
    )
    livox_demo.add_argument("--data-dir", type=Path, default=Path("data/public"))
    livox_demo.add_argument(
        "--output-dir",
        type=Path,
        default=Path("outputs/livox_horizon_horizon_pcd_sample"),
    )
    livox_demo.add_argument(
        "--no-download",
        action="store_true",
        help="use existing local PCD files instead of downloading",
    )
    livox_demo.add_argument(
        "--strict-assessment",
        action="store_true",
        help="return non-zero unless the falsification assessment is PASS",
    )
    livox_demo.add_argument("--seed", type=int)
    livox_demo.add_argument("--json", action="store_true")
    livox_demo.set_defaults(func=_cmd_demo_livox_evidence)

    six_dof_demo = demo_subcommands.add_parser(
        "kitti-six-dof",
        help="compare CPU/candidate six-DoF calibration on 25 frozen KITTI raw frames",
    )
    six_dof_demo.add_argument("sequence", type=Path, help="synced KITTI raw drive directory")
    six_dof_demo.add_argument("depth_provider", type=Path, help="verified frozen depth manifest")
    six_dof_demo.add_argument(
        "--output-dir", type=Path, default=Path("outputs/kitti-six-dof-demo"),
        help="new or empty directory for results and offline comparison HTML",
    )
    six_dof_demo.add_argument(
        "--candidate-backend", choices=("cuda", "numba_cpu", "numpy"), default="cuda",
        help="explicit backend; numpy runs a CPU replay for machines without a GPU",
    )
    six_dof_demo.add_argument("--cuda-cache-mib", type=int)
    six_dof_demo.add_argument(
        "--candidate-frame-workers", type=int, default=1,
        help="CPU candidate frame threads; NumPy reference stays serial; CUDA requires 1",
    )
    six_dof_demo.add_argument("--max-evaluations", type=int, default=800)
    six_dof_demo.add_argument(
        "--reuse-verified-inputs", action="store_true",
        help="capture immutable inputs once; include initial verification cost in pipeline timing",
    )
    six_dof_demo.add_argument(
        "--repetitions", type=int, default=1,
        help="invocations per backend; starts from the shared prior and alternates execution order",
    )
    six_dof_demo.add_argument("--rotation-offset-deg", type=float, nargs=3, default=(0.5, 0.0, 0.0))
    six_dof_demo.add_argument(
        "--translation-offset-m", type=float, nargs=3, default=(0.5, 0.0, 0.0)
    )
    six_dof_demo.add_argument("--json", action="store_true")
    six_dof_demo.set_defaults(func=_cmd_demo_kitti_six_dof)

    six_dof_sweep = demo_subcommands.add_parser(
        "kitti-six-dof-sweep",
        help="compare six fixed signed-axis initializations; CPU-only cases support processes",
    )
    six_dof_sweep.add_argument("sequence", type=Path)
    six_dof_sweep.add_argument("depth_provider", type=Path)
    six_dof_sweep.add_argument(
        "--output-dir", type=Path, default=Path("outputs/kitti-six-dof-sweep")
    )
    six_dof_sweep.add_argument(
        "--candidate-backend", choices=("cuda", "numba_cpu", "numpy"), default="cuda"
    )
    six_dof_sweep.add_argument("--workers", type=int, default=1)
    six_dof_sweep.add_argument("--candidate-frame-workers", type=int, default=1)
    six_dof_sweep.add_argument("--repetitions", type=int, default=1)
    six_dof_sweep.add_argument(
        "--reuse-verified-inputs", action="store_true",
        help="verify/capture once inside each case; worker processes own separate snapshots",
    )
    six_dof_sweep.add_argument("--rotation-deg", type=float, default=0.5)
    six_dof_sweep.add_argument("--translation-m", type=float, default=0.5)
    six_dof_sweep.add_argument("--cuda-cache-mib", type=int)
    six_dof_sweep.add_argument("--max-evaluations", type=int, default=800)
    six_dof_sweep.add_argument("--json", action="store_true")
    six_dof_sweep.set_defaults(func=_cmd_demo_kitti_six_dof_sweep)

    kitti_demo = demo_subcommands.add_parser(
        "kitti-lidar-camera-evidence",
        help=(
            "recompute KITTI raw camera-LiDAR overlay evidence artifacts "
            "(diagnostic overlay on the LiDAR candidate, not a standalone "
            "camera calibration)"
        ),
    )
    kitti_demo.add_argument(
        "--config",
        type=Path,
        default=_packaged_kitti_lidar_camera_demo_config(),
        help="base KITTI camera-LiDAR evidence config (defaults to the packaged fixture)",
    )
    kitti_demo.add_argument(
        "--dataset-path",
        type=Path,
        default=None,
        help=(
            "KITTI raw sequence directory (for example one obtained through the "
            "official KITTI raw download flow); defaults to the small synthetic "
            "fixture bundled with the example config"
        ),
    )
    kitti_demo.add_argument(
        "--output-dir",
        type=Path,
        default=Path("outputs/kitti_lidar_camera_evidence"),
    )
    kitti_demo.add_argument(
        "--strict-assessment",
        action="store_true",
        help="return non-zero unless the falsification assessment is PASS",
    )
    kitti_demo.add_argument("--seed", type=int)
    kitti_demo.add_argument("--json", action="store_true")
    kitti_demo.set_defaults(func=_cmd_demo_kitti_lidar_camera_evidence)
    kitti_benchmark = demo_subcommands.add_parser(
        "kitti-falsification-benchmark",
        help="run the pinned full-scale KITTI reference vs known-bad benchmark",
    )
    kitti_benchmark.add_argument("dataset_path", type=Path)
    kitti_benchmark.add_argument(
        "--config",
        type=Path,
        default=Path("examples/public_datasets/kitti_raw_2011_09_26_drive_0005/config.yaml"),
    )
    kitti_benchmark.add_argument(
        "--output-dir",
        type=Path,
        default=Path("outputs/kitti_falsification_benchmark"),
    )
    kitti_benchmark.add_argument("--max-frames", type=_positive_int, default=50)
    kitti_benchmark.add_argument("--projection-sample-points", type=_positive_int, default=4000)
    kitti_benchmark.add_argument("--seed", type=int, default=20260729)
    kitti_benchmark.add_argument(
        "--source-url",
        default="https://www.cvlibs.net/datasets/kitti/raw_data.php",
    )
    kitti_benchmark.add_argument(
        "--source-note",
        default="official KITTI raw download; user-supplied local copy",
    )
    kitti_benchmark.add_argument(
        "--enforce",
        action="store_true",
        help="return non-zero unless reference PASSes and known-bad FAILs",
    )
    kitti_benchmark.add_argument("--json", action="store_true")
    kitti_benchmark.set_defaults(func=_cmd_demo_kitti_falsification_benchmark)

    convert = subcommands.add_parser("convert", help="convert a public dataset into a rosbag2 bag")
    convert_subcommands = convert.add_subparsers(dest="convert_command", required=True)
    convert_kitti = convert_subcommands.add_parser(
        "kitti-raw",
        help="write a KITTI raw drive (Velodyne, OXTS, calibration) as a rosbag2 bag",
        description=(
            "Write /velodyne_points, /oxts/imu, /oxts/fix, /oxts/odometry (INS pose and "
            "body-frame twist), /oxts/twist (wheel proxy) and a transient-local /tf_static "
            "from calib_imu_to_velo.txt. base_link is defined as the OXTS/IMU frame; the "
            "Velodyne cloud has no per-point time field because KITTI raw has none."
        ),
    )
    convert_kitti.add_argument(
        "drives",
        type=Path,
        nargs="+",
        help="KITTI raw *_sync drive(s) of one calibration, e.g. 2011_09_26_drive_0005_sync",
    )
    convert_kitti.add_argument(
        "--calib-dir",
        type=Path,
        default=None,
        help="directory with calib_imu_to_velo.txt (default: the drive's parent directory)",
    )
    convert_kitti.add_argument(
        "--camera",
        default=None,
        metavar="DIR",
        help="also write this camera (for example image_02): /camera/image_raw, "
        "/camera/camera_info and the imu_link to camera tf, so camera-lidar can be checked",
    )
    convert_kitti.add_argument(
        "--velodyne-time",
        choices=("none", "azimuth"),
        default="none",
        help="per-point time of the Velodyne sweeps: none (rigid snapshots, the default) or "
        "azimuth (each point's time modelled from its azimuth and the sweep's start and end "
        "timestamps, so camera-lidar and the deskewing pairs can move points at speed)",
    )
    convert_kitti.add_argument("--output", type=Path, required=True, help="bag directory to write")
    convert_kitti.add_argument("--overwrite", action="store_true", help="replace an existing bag")
    convert_kitti.add_argument("--json", action="store_true")
    convert_kitti.set_defaults(func=_cmd_convert_kitti_raw)

    convert_360 = convert_subcommands.add_parser(
        "kitti-360",
        help="write KITTI-360 rectified perspective images, Velodyne and poses as rosbag2",
    )
    convert_360.add_argument("dataset_root", type=Path, help="root of the official split layout")
    convert_360.add_argument("--sequence", required=True, help="2013_05_28_drive_NNNN_sync")
    convert_360.add_argument("--calib-dir", type=Path, default=None)
    convert_360.add_argument("--camera", choices=("image_00", "image_01"), default="image_00")
    convert_360.add_argument(
        "--velodyne-time",
        choices=("none", "azimuth"),
        default="azimuth",
        help="per-point time model (default: azimuth); none keeps rigid scans",
    )
    convert_360.add_argument(
        "--scan-period",
        type=_positive_float,
        default=0.1,
        metavar="SECONDS",
        help="declared period for the azimuth model, not measured firing times (default: 0.1)",
    )
    convert_360.add_argument("--start-frame", type=int, default=0)
    convert_360.add_argument("--max-frames", type=_positive_int, default=None)
    convert_360.add_argument("--output", type=Path, required=True)
    convert_360.add_argument("--overwrite", action="store_true")
    convert_360.add_argument("--json", action="store_true")
    convert_360.set_defaults(func=_cmd_convert_kitti360)

    kitti = subcommands.add_parser("kitti", help="KITTI raw utilities")
    kitti_subcommands = kitti.add_subparsers(dest="kitti_command", required=True)
    kitti_import = kitti_subcommands.add_parser(
        "import-calib",
        help="import KITTI calibration files as Calibrex transforms",
    )
    kitti_import.add_argument("path", type=Path, help="directory containing calib_velo_to_cam.txt")
    kitti_import.add_argument("--output", type=Path)
    kitti_import.add_argument("--json", action="store_true")
    kitti_import.set_defaults(func=_cmd_kitti_import_calib)
    kitti_lock = kitti_subcommands.add_parser(
        "lock-benchmark-input",
        help="inspect and digest-lock the fixed KITTI raw 0005 benchmark inputs",
    )
    kitti_lock.add_argument(
        "path",
        type=Path,
        help="2011_09_26_drive_0005_sync sequence directory",
    )
    kitti_lock.add_argument("--output", type=Path, required=True)
    kitti_lock.add_argument("--json", action="store_true")
    kitti_lock.set_defaults(func=_cmd_kitti_lock_benchmark_input)
    kitti_i2i = kitti_subcommands.add_parser(
        "benchmark-i2i",
        help="benchmark baseline versus coarse native I2I recovery on locked KITTI inputs",
    )
    kitti_i2i.add_argument("input_manifest", type=Path)
    kitti_i2i.add_argument("--sequence-path", type=Path)
    kitti_i2i.add_argument("--definition-output", type=Path, required=True)
    kitti_i2i.add_argument("--output", type=Path, required=True)
    kitti_i2i.add_argument("--max-points-per-frame", type=_positive_int, default=2_000)
    kitti_i2i.add_argument("--max-iterations", type=int, default=20)
    kitti_i2i.add_argument("--json", action="store_true")
    kitti_i2i.set_defaults(func=_cmd_kitti_benchmark_i2i)

    gnss_lidar = subcommands.add_parser(
        "gnss-lidar",
        help="GNSS antenna lever arm and clock offset against LiDAR odometry",
    )
    gnss_lidar_subcommands = gnss_lidar.add_subparsers(dest="gnss_lidar_command", required=True)
    gnss_lidar_rtk = gnss_lidar_subcommands.add_parser(
        "rtk-slam",
        help="calibrate the antenna lever arm from RTK-SLAM rosbag2 sequences and rtk.txt",
    )
    gnss_lidar_rtk.add_argument(
        "--bag", type=Path, action="append", required=True, help="rosbag2 directory (repeatable)"
    )
    gnss_lidar_rtk.add_argument(
        "--rtk", type=Path, action="append", required=True, help="rtk.txt, one per --bag"
    )
    gnss_lidar_rtk.add_argument("--calib", type=Path, required=True, help="RTK-SLAM calib.yaml")
    gnss_lidar_rtk.add_argument("--output", type=Path, required=True)
    gnss_lidar_rtk.add_argument("--topic", default="/livox/points")
    gnss_lidar_rtk.add_argument("--max-scans", type=_positive_int)
    gnss_lidar_rtk.add_argument(
        "--max-seconds",
        type=_positive_float,
        help="use only the scans within S seconds of each sequence's first scan",
    )
    gnss_lidar_rtk.add_argument("--json", action="store_true")
    gnss_lidar_rtk.set_defaults(func=_cmd_gnss_lidar_rtk_slam)

    imu_lidar = subcommands.add_parser(
        "imu-lidar",
        help="IMU-LiDAR rotation, clock offset, and gyro bias from angular rates",
    )
    imu_lidar_subcommands = imu_lidar.add_subparsers(dest="imu_lidar_command", required=True)
    imu_lidar_livox = imu_lidar_subcommands.add_parser(
        "livox",
        help="calibrate a Livox built-in IMU against LiDAR odometry from ROS 2 bags",
    )
    imu_lidar_livox.add_argument(
        "bags", type=Path, nargs="+", help="rosbag2 directories of one rig"
    )
    imu_lidar_livox.add_argument(
        "--profile",
        required=True,
        choices=profile_choices,
        help="topic and unit conventions of the recording",
    )
    imu_lidar_livox.add_argument("--dataset-family", required=True)
    imu_lidar_livox.add_argument("--dataset-license", required=True)
    imu_lidar_livox.add_argument(
        "--no-mid360-reference",
        action="store_true",
        help="do not compare with the MID360 design rotation",
    )
    imu_lidar_livox.add_argument("--max-scans", type=_positive_int)
    imu_lidar_livox.add_argument("--output", type=Path, required=True)
    imu_lidar_livox.add_argument("--json", action="store_true")
    imu_lidar_livox.set_defaults(func=_cmd_imu_lidar_livox)
    imu_lidar_translation = imu_lidar_subcommands.add_parser(
        "livox-translation",
        help="calibrate the IMU lever arm of a Livox rig from the accelerometer, "
        "given a calibrated rotation",
    )
    imu_lidar_translation.add_argument(
        "bags", type=Path, nargs="+", help="rosbag2 directories of one rig"
    )
    imu_lidar_translation.add_argument(
        "--profile",
        required=True,
        choices=profile_choices,
        help="topic and unit conventions of the recording",
    )
    imu_lidar_translation.add_argument(
        "--rotation",
        type=Path,
        required=True,
        help="slac.imu_lidar_rotation/v0.1 artifact of the same rig (rotation, dt, gyro bias)",
    )
    imu_lidar_translation.add_argument("--dataset-family", required=True)
    imu_lidar_translation.add_argument("--dataset-license", required=True)
    imu_lidar_translation.add_argument(
        "--no-mid360-reference",
        action="store_true",
        help="do not compare with the MID360 design translation",
    )
    imu_lidar_translation.add_argument("--max-scans", type=_positive_int)
    imu_lidar_translation.add_argument("--output", type=Path, required=True)
    imu_lidar_translation.add_argument("--json", action="store_true")
    imu_lidar_translation.set_defaults(func=_cmd_imu_lidar_livox_translation)
    imu_lidar_trajectory = imu_lidar_subcommands.add_parser(
        "trajectory",
        help="calibrate an IMU against a sensor trajectory (TUM) without bags; "
        "the same computation runs in the browser",
    )
    imu_lidar_trajectory.add_argument(
        "--imu", type=Path, required=True, help="CSV with t, gx, gy, gz, ax, ay, az"
    )
    imu_lidar_trajectory.add_argument(
        "--trajectory", type=Path, required=True, help="TUM trajectory T_world_sensor"
    )
    imu_lidar_trajectory.add_argument("--acceleration-unit", choices=["mps2", "g"], default="mps2")
    imu_lidar_trajectory.add_argument(
        "--mid360-reference",
        action="store_true",
        help="compare with the Livox MID360 design extrinsic",
    )
    imu_lidar_trajectory.add_argument("--rotation-only", action="store_true")
    imu_lidar_trajectory.add_argument("--dataset-family", default="user")
    imu_lidar_trajectory.add_argument("--dataset-license", default="user-provided")
    imu_lidar_trajectory.add_argument("--output-rotation", type=Path, required=True)
    imu_lidar_trajectory.add_argument("--output-translation", type=Path)
    imu_lidar_trajectory.add_argument("--json", action="store_true")
    imu_lidar_trajectory.set_defaults(func=_cmd_imu_lidar_trajectory)
    imu_lidar_joint = imu_lidar_subcommands.add_parser(
        "joint",
        help="jointly calibrate IMU rotation, lever arm, clock offset, biases and gravity "
        "against LiDAR on a B-spline trajectory from one bag",
    )
    imu_lidar_joint.add_argument("bag", type=Path, help="rosbag2 directory, .db3, .mcap or .bag")
    imu_lidar_joint.add_argument("--lidar-topic", required=True, help="PointCloud2 topic")
    imu_lidar_joint.add_argument("--imu-topic", required=True, help="sensor_msgs/Imu topic")
    imu_lidar_joint.add_argument(
        "--acceleration-unit",
        choices=("mps2", "g"),
        default="mps2",
        help="unit of the IMU linear acceleration (Livox reports g)",
    )
    imu_lidar_joint.add_argument("--dataset-family", required=True)
    imu_lidar_joint.add_argument("--dataset-license", required=True)
    imu_lidar_joint.add_argument(
        "--max-seconds", type=_positive_float, help="read only this many seconds of the bag"
    )
    imu_lidar_joint.add_argument(
        "--max-rounds",
        type=_positive_int,
        default=8,
        help="map rounds (re-associate LiDAR returns, refit) before giving up on convergence",
    )
    imu_lidar_joint.add_argument(
        "--imu-lowpass-hz",
        type=_positive_float,
        help="zero-phase low-pass the IMU at this cutoff and resample at twice it before the "
        "fit (for platform vibration far above the spline bandwidth)",
    )
    imu_lidar_joint.add_argument(
        "--odometry-backend", choices=("cpu", "cuda"), default="cpu",
        help="backend for initial and gyro-deskewed scan odometry (CUDA is optional)",
    )
    imu_lidar_joint.add_argument(
        "--fit-plane-backend", choices=("numpy", "cuda"), default="numpy",
        help="backend for spline plane residuals and systems (CUDA is optional)",
    )
    imu_lidar_joint.add_argument(
        "--resident-odometry", action="store_true",
        help="keep odometry geometry on CUDA; requires --odometry-backend cuda and all "
        "three explicit odometry geometry/motion quanta",
    )
    imu_lidar_joint.add_argument(
        "--odometry-voxel-size-m", type=_positive_float,
        help="voxel size for scan odometry; smaller values retain denser geometry",
    )
    imu_lidar_joint.add_argument(
        "--odometry-local-map-scans", type=_positive_int,
        help="number of recent scans used by odometry",
    )
    imu_lidar_joint.add_argument(
        "--odometry-query-workers", type=_positive_int,
        help="CPU threads for scan-odometry nearest-neighbor queries (default: 1)",
    )
    imu_lidar_joint.add_argument(
        "--odometry-geometry-quantum-m", type=_positive_float,
        help="optional coordinate grid for reproducible odometry geometry (off by default)",
    )
    imu_lidar_joint.add_argument(
        "--odometry-motion-translation-quantum-m", type=_positive_float,
        help="optional translation grid for accepted scan motions (off by default)",
    )
    imu_lidar_joint.add_argument(
        "--odometry-motion-rotation-quantum-rad", type=_positive_float,
        help="optional rotation-vector grid for accepted scan motions (off by default)",
    )
    imu_lidar_joint.add_argument("--output", type=Path, required=True)
    imu_lidar_joint.add_argument("--json", action="store_true")
    imu_lidar_joint.set_defaults(func=_cmd_imu_lidar_joint)

    camera_imu = subcommands.add_parser(
        "camera-imu",
        help="targetless camera-IMU rotation, clock offset, and gyro bias from images",
    )
    camera_imu_subcommands = camera_imu.add_subparsers(dest="camera_imu_command", required=True)
    camera_imu_rotation = camera_imu_subcommands.add_parser(
        "rotation",
        help="align camera rotations from tracked features with the gyro (needs calibrex[opencv])",
    )
    camera_imu_rotation.add_argument(
        "bags", type=Path, nargs="+", help="rosbag2 directories of one rig"
    )
    camera_imu_rotation.add_argument(
        "--camchain",
        type=Path,
        required=True,
        help="Kalibr camchain(-imucam) YAML with the camera's intrinsics",
    )
    camera_imu_rotation.add_argument("--camera", default="cam0", help="camera key in the camchain")
    camera_imu_rotation.add_argument("--imu-topic", required=True)
    camera_imu_rotation.add_argument(
        "--image-topic", help="defaults to the camchain's rostopic for the camera"
    )
    camera_imu_rotation.add_argument("--acceleration-unit", choices=["mps2", "g"], default="mps2")
    camera_imu_rotation.add_argument(
        "--no-reference",
        action="store_true",
        help="do not compare with the camchain's T_cam_imu",
    )
    camera_imu_rotation.add_argument("--frame-stride", type=_positive_int, default=4)
    camera_imu_rotation.add_argument("--max-seconds", type=float)
    camera_imu_rotation.add_argument(
        "--observable-rotation-std-deg",
        type=float,
        help="reported std above which a rotation axis is unobservable (camera default 0.3)",
    )
    camera_imu_rotation.add_argument(
        "--min-window-rotation-deg",
        type=float,
        help="leave out windows that rotate less than this (camera default 1.0; 0 keeps all)",
    )
    camera_imu_rotation.add_argument("--dataset-family", required=True)
    camera_imu_rotation.add_argument("--dataset-license", required=True)
    camera_imu_rotation.add_argument("--output", type=Path, required=True)
    camera_imu_rotation.add_argument("--json", action="store_true")
    camera_imu_rotation.set_defaults(func=_cmd_camera_imu_rotation)
    camera_imu_focal = camera_imu_subcommands.add_parser(
        "focal",
        help="check a camera's focal lengths against the gyro (no target; needs a "
        "camera-imu rotation artifact)",
    )
    camera_imu_focal.add_argument("bag", type=Path, help="rosbag2 directory")
    camera_imu_focal.add_argument("--camchain", type=Path, required=True)
    camera_imu_focal.add_argument("--camera", default="cam0")
    camera_imu_focal.add_argument("--imu-topic", required=True)
    camera_imu_focal.add_argument("--image-topic")
    camera_imu_focal.add_argument(
        "--rotation", type=Path, required=True, help="camera-imu rotation artifact"
    )
    camera_imu_focal.add_argument("--frame-stride", type=_positive_int, default=4)
    camera_imu_focal.add_argument("--dataset-family", required=True)
    camera_imu_focal.add_argument("--dataset-license", required=True)
    camera_imu_focal.add_argument("--output", type=Path, required=True)
    camera_imu_focal.add_argument("--json", action="store_true")
    camera_imu_focal.set_defaults(func=_cmd_camera_imu_focal)

    lidar_lidar = subcommands.add_parser(
        "lidar-lidar",
        help="LiDAR-LiDAR extrinsic from registering one LiDAR's scans to the other's maps",
    )
    lidar_lidar_subcommands = lidar_lidar.add_subparsers(dest="lidar_lidar_command", required=True)
    lidar_lidar_ros2 = lidar_lidar_subcommands.add_parser(
        "ros2", help="calibrate T_reference_target for two LiDARs in one ROS 2 bag"
    )
    lidar_lidar_ros2.add_argument("bag", type=Path, help="rosbag2 directory")
    lidar_lidar_ros2.add_argument("--reference-topic", required=True)
    lidar_lidar_ros2.add_argument("--target-topic", required=True)
    lidar_lidar_ros2.add_argument(
        "--point-time-field", help="per-point time field used to deskew the reference odometry"
    )
    lidar_lidar_ros2.add_argument(
        "--initial", type=Path, help="initial T_reference_target (4x4 YAML/JSON or OpenCV YAML)"
    )
    lidar_lidar_ros2.add_argument(
        "--body-transforms",
        type=Path,
        nargs=2,
        metavar=("REFERENCE", "TARGET"),
        help="T_body_reference and T_body_target files; their composition is both the "
        "initial value and the reference compared against",
    )
    lidar_lidar_ros2.add_argument("--max-seconds", type=float)
    lidar_lidar_ros2.add_argument("--registration-backend", choices=("cpu", "cuda"), default="cpu")
    lidar_lidar_ros2.add_argument(
        "--registration-query-workers", type=_positive_int, default=1,
        help="CPU workers for map correspondences and native normal neighborhoods (default: 1)",
    )
    lidar_lidar_ros2.add_argument("--odometry-backend", choices=("cpu", "cuda"), default="cpu")
    lidar_lidar_ros2.add_argument("--dataset-family", required=True)
    lidar_lidar_ros2.add_argument("--dataset-license", required=True)
    lidar_lidar_ros2.add_argument("--output", type=Path, required=True)
    lidar_lidar_ros2.add_argument("--json", action="store_true")
    lidar_lidar_ros2.set_defaults(func=_cmd_lidar_lidar_ros2)

    lidar_vehicle = subcommands.add_parser(
        "lidar-vehicle",
        help="LiDAR-to-vehicle rotation from the vehicle's non-holonomic motion",
    )
    lidar_vehicle_subcommands = lidar_vehicle.add_subparsers(
        dest="lidar_vehicle_command", required=True
    )
    lidar_vehicle_kitti = lidar_vehicle_subcommands.add_parser(
        "kitti", help="R_vehicle_velodyne from KITTI raw drives of one calibration"
    )
    lidar_vehicle_kitti.add_argument("drives", type=Path, nargs="+", help="KITTI raw *_sync drives")
    lidar_vehicle_kitti.add_argument("--output", type=Path, required=True)
    lidar_vehicle_kitti.add_argument("--json", action="store_true")
    lidar_vehicle_kitti.set_defaults(func=_cmd_lidar_vehicle_kitti)

    imu_vehicle = subcommands.add_parser(
        "imu-vehicle",
        help="INS/IMU-to-vehicle rotation from the vehicle's non-holonomic motion",
    )
    imu_vehicle_subcommands = imu_vehicle.add_subparsers(
        dest="imu_vehicle_command", required=True
    )
    imu_vehicle_kitti = imu_vehicle_subcommands.add_parser(
        "kitti", help="R_vehicle_imu for the KITTI OXTS unit from its body-frame velocity"
    )
    imu_vehicle_kitti.add_argument("drives", type=Path, nargs="+", help="KITTI raw *_sync drives")
    imu_vehicle_kitti.add_argument(
        "--lidar-vehicle",
        type=Path,
        help="a lidar-vehicle artifact of the same rig, for the closure reference",
    )
    imu_vehicle_kitti.add_argument("--output", type=Path, required=True)
    imu_vehicle_kitti.add_argument("--json", action="store_true")
    imu_vehicle_kitti.set_defaults(func=_cmd_imu_vehicle_kitti)

    gnss_imu = subcommands.add_parser(
        "gnss-imu", help="GNSS antenna lever arm in the IMU frame"
    )
    gnss_imu_subcommands = gnss_imu.add_subparsers(dest="gnss_imu_command", required=True)
    gnss_imu_compose = gnss_imu_subcommands.add_parser(
        "compose",
        help="compose GNSS-LiDAR and IMU-LiDAR artifacts into the GNSS-IMU lever arm",
    )
    gnss_imu_compose.add_argument("--gnss-lidar", type=Path, required=True)
    gnss_imu_compose.add_argument("--imu-lidar-rotation", type=Path, required=True)
    gnss_imu_compose.add_argument("--imu-lidar-translation", type=Path, required=True)
    gnss_imu_compose.add_argument(
        "--reference", type=float, nargs=3, metavar=("X", "Y", "Z"),
        help="reference antenna position in the IMU frame (m), compared after composing",
    )
    gnss_imu_compose.add_argument("--reference-name")
    gnss_imu_compose.add_argument("--output", type=Path, required=True)
    gnss_imu_compose.add_argument("--json", action="store_true")
    gnss_imu_compose.set_defaults(func=_cmd_gnss_imu_compose)

    lidar_wheel = subcommands.add_parser(
        "lidar-wheel",
        help="LiDAR-to-vehicle rotation, wheel-speed scale, and clock offset vs wheel odometry",
    )
    lidar_wheel_subcommands = lidar_wheel.add_subparsers(
        dest="lidar_wheel_command", required=True
    )
    lidar_wheel_trajectory = lidar_wheel_subcommands.add_parser(
        "trajectory", help="from a LiDAR trajectory (TUM) and a wheel CSV (t, speed, yaw_rate)"
    )
    lidar_wheel_trajectory.add_argument("--trajectory", type=Path, required=True)
    lidar_wheel_trajectory.add_argument("--wheel", type=Path, required=True)
    lidar_wheel_trajectory.add_argument("--dataset-family", default="user")
    lidar_wheel_trajectory.add_argument("--dataset-license", default="user-provided")
    lidar_wheel_trajectory.add_argument("--output", type=Path, required=True)
    lidar_wheel_trajectory.add_argument("--json", action="store_true")
    lidar_wheel_trajectory.set_defaults(func=_cmd_lidar_wheel_trajectory)
    lidar_wheel_kitti = lidar_wheel_subcommands.add_parser(
        "kitti", help="KITTI raw, with the OXTS speed and yaw rate standing in for wheels"
    )
    lidar_wheel_kitti.add_argument("drives", type=Path, nargs="+")
    lidar_wheel_kitti.add_argument("--lidar-vehicle", type=Path)
    lidar_wheel_kitti.add_argument("--output", type=Path, required=True)
    lidar_wheel_kitti.add_argument("--json", action="store_true")
    lidar_wheel_kitti.set_defaults(func=_cmd_lidar_wheel_kitti)

    ins_lidar = subcommands.add_parser(
        "ins-lidar",
        help="INS/GNSS-LiDAR trajectory hand-eye calibration evidence",
    )
    ins_lidar_subcommands = ins_lidar.add_subparsers(dest="ins_lidar_command", required=True)
    ins_lidar_kitti = ins_lidar_subcommands.add_parser(
        "kitti",
        help="calibrate T_imu_velo from KITTI raw OXTS and Velodyne (pool same-rig drives)",
    )
    ins_lidar_kitti.add_argument("drives", type=Path, nargs="+", help="KITTI raw *_sync drives")
    ins_lidar_kitti.add_argument("--output", type=Path, required=True)
    ins_lidar_kitti.add_argument("--max-frames", type=_positive_int)
    ins_lidar_kitti.add_argument("--block-duration", type=float, default=5.0)
    ins_lidar_kitti.add_argument(
        "--prior",
        action="append",
        default=[],
        metavar="DOF=VALUE:SIGMA",
        help="Gaussian prior on x, y, z (m) or time_offset (s), e.g. z=0.80:0.02 (repeatable)",
    )
    ins_lidar_kitti.add_argument("--json", action="store_true")
    ins_lidar_kitti.set_defaults(func=_cmd_ins_lidar_kitti)

    sota = subcommands.add_parser(
        "sota",
        help="pair-agnostic SOTA claim audits and per-pair standings",
    )
    sota_subcommands = sota.add_subparsers(dest="sota_command", required=True)
    sota_audit_generic = sota_subcommands.add_parser(
        "audit",
        help="evaluate a digest-frozen SOTA claim protocol for any sensor pair",
    )
    sota_audit_generic.add_argument("protocol", type=Path)
    sota_audit_generic.add_argument("--output", type=Path, required=True)
    sota_audit_generic.add_argument("--audit-id")
    sota_audit_generic.add_argument("--json", action="store_true")
    sota_audit_generic.set_defaults(func=_cmd_sota_audit)
    sota_leaderboard = sota_subcommands.add_parser(
        "leaderboard",
        help="collect SOTA audit results into per-pair standings",
    )
    sota_leaderboard.add_argument("audits", type=Path, nargs="*")
    sota_leaderboard.add_argument("--output", type=Path, required=True)
    sota_leaderboard.add_argument(
        "--target-pair",
        action="append",
        default=[],
        help="pair to list even without an audit, e.g. gnss-lidar (repeatable)",
    )
    sota_leaderboard.add_argument("--markdown", type=Path, help="also write a Markdown table")
    sota_leaderboard.add_argument("--json", action="store_true")
    sota_leaderboard.set_defaults(func=_cmd_sota_leaderboard)

    camera_lidar = subcommands.add_parser(
        "camera-lidar",
        help="schema-valid camera-LiDAR research benchmark utilities",
    )
    camera_lidar_subcommands = camera_lidar.add_subparsers(
        dest="camera_lidar_command",
        required=True,
    )
    build_kitti_problem = camera_lidar_subcommands.add_parser(
        "build-kitti-problem",
        help="bind a frozen depth-provider artifact to KITTI raw Velodyne scans",
    )
    build_kitti_problem.add_argument(
        "sequence_path",
        type=Path,
        help="KITTI *_sync sequence directory",
    )
    build_kitti_problem.add_argument("depth_provider", type=Path)
    build_kitti_problem.add_argument("--output", type=Path, required=True)
    build_kitti_problem.add_argument("--camera-stream", default="image_02")
    build_kitti_problem.add_argument("--lidar-directory", type=Path)
    build_kitti_problem.add_argument("--lidar-manifest", type=Path)
    build_kitti_problem.add_argument("--dataset-id")
    build_kitti_problem.add_argument("--problem-id")
    build_kitti_problem.add_argument("--rotation-bound-deg", type=float, default=20.0)
    build_kitti_problem.add_argument(
        "--translation-bound-m",
        type=float,
        default=0.0,
    )
    build_kitti_problem.add_argument("--json", action="store_true")
    build_kitti_problem.set_defaults(func=_cmd_camera_lidar_build_kitti_problem)
    build_kitti360_problem = camera_lidar_subcommands.add_parser(
        "build-kitti360-problem",
        help="bind a frozen depth-provider artifact to KITTI-360 raw scans",
    )
    build_kitti360_problem.add_argument("sequence_path", type=Path)
    build_kitti360_problem.add_argument("depth_provider", type=Path)
    build_kitti360_problem.add_argument("--output", type=Path, required=True)
    build_kitti360_problem.add_argument("--calibration-root", type=Path)
    build_kitti360_problem.add_argument("--lidar-directory", type=Path)
    build_kitti360_problem.add_argument("--lidar-manifest", type=Path)
    build_kitti360_problem.add_argument("--camera-stream", default="image_03")
    build_kitti360_problem.add_argument("--split-id", default="evaluation")
    build_kitti360_problem.add_argument("--dataset-id")
    build_kitti360_problem.add_argument("--problem-id")
    build_kitti360_problem.add_argument("--rotation-bound-deg", type=float, default=20.0)
    build_kitti360_problem.add_argument(
        "--translation-bound-m",
        type=float,
        default=0.0,
    )
    build_kitti360_problem.add_argument("--json", action="store_true")
    build_kitti360_problem.set_defaults(func=_cmd_camera_lidar_build_kitti360_problem)
    build_probabilistic_correspondence = camera_lidar_subcommands.add_parser(
        "build-probabilistic-correspondence",
        help="validate provider NPZ exports and build a probabilistic correspondence artifact",
    )
    build_probabilistic_correspondence.add_argument("export_manifest", type=Path)
    build_probabilistic_correspondence.add_argument("--output", type=Path, required=True)
    build_probabilistic_correspondence.add_argument("--json", action="store_true")
    build_probabilistic_correspondence.set_defaults(
        func=_cmd_camera_lidar_build_probabilistic_correspondence
    )
    build_a2d2_problem = camera_lidar_subcommands.add_parser(
        "build-a2d2-problem",
        help="build the pre-registered A2D2 cross-family D2D smoke problem",
    )
    build_a2d2_problem.add_argument("data_directory", type=Path)
    build_a2d2_problem.add_argument("depth_provider", type=Path)
    build_a2d2_problem.add_argument("--lidar-output-directory", type=Path, required=True)
    build_a2d2_problem.add_argument("--lidar-manifest-output", type=Path, required=True)
    build_a2d2_problem.add_argument("--output", type=Path, required=True)
    build_a2d2_problem.add_argument("--problem-id")
    build_a2d2_problem.add_argument("--rotation-bound-deg", type=float, default=20.0)
    build_a2d2_problem.add_argument("--json", action="store_true")
    build_a2d2_problem.set_defaults(func=_cmd_camera_lidar_build_a2d2_problem)
    koide_pilot = camera_lidar_subcommands.add_parser(
        "benchmark-koide-pilot",
        help=(
            "accept a frozen external Koide candidate on a KITTI frame/temporal "
            "holdout with mandatory six-DoF controls"
        ),
    )
    koide_pilot.add_argument("dataset_path", type=Path)
    koide_pilot.add_argument(
        "--candidate",
        type=Path,
        help="official native calib.json or schema-valid external-run artifact",
    )
    koide_pilot.add_argument("--config", type=Path, required=False)
    koide_pilot.add_argument("--readiness", type=Path, required=False)
    koide_pilot.add_argument("--input-manifest", type=Path)
    koide_pilot.add_argument("--output-dir", type=Path, required=True)
    koide_pilot.add_argument("--camera-frame", default="camera0")
    koide_pilot.add_argument("--lidar-frame", default="lidar0")
    koide_pilot.add_argument("--camera-stream", default="image_02")
    koide_pilot.add_argument("--lidar-stream", default="velodyne_points")
    koide_pilot.add_argument("--max-frames", type=_positive_int, default=50)
    koide_pilot.add_argument("--max-points", type=_positive_int, default=4000)
    koide_pilot.add_argument("--holdout-ratio", type=float, default=0.2)
    koide_pilot.add_argument("--split-seed", type=int, default=20260823)
    koide_pilot.add_argument("--min-holdout-projection-ratio", type=float, default=0.50)
    koide_pilot.add_argument("--min-holdout-edge-alignment", type=float, default=0.20)
    koide_pilot.add_argument("--min-holdout-depth-edge-alignment", type=float, default=0.20)
    koide_pilot.add_argument("--known-bad-min-metric-delta", type=float, default=0.01)
    koide_pilot.add_argument(
        "--official-command",
        help="exact official command as one shell-like string (recorded, never shell-executed)",
    )
    koide_pilot.add_argument("--tool-source-commit")
    koide_pilot.add_argument("--container-digest")
    koide_pilot.add_argument("--json", action="store_true")
    koide_pilot.set_defaults(func=_cmd_camera_lidar_benchmark_koide_pilot)
    koide_handoff = camera_lidar_subcommands.add_parser(
        "koide-handoff",
        help=(
            "validate the pinned commercial Koide lock and print the exact next "
            "operator actions; never executes Docker or Koide"
        ),
    )
    koide_handoff.add_argument(
        "--lock",
        type=Path,
        default=Path("examples/official/koide_execution_lock.yaml"),
        help="schema-valid immutable Koide execution lock",
    )
    koide_handoff.add_argument("--json", action="store_true")
    koide_handoff.set_defaults(func=_cmd_camera_lidar_koide_handoff)
    koide_real_plan = camera_lidar_subcommands.add_parser(
        "koide-real-plan",
        aliases=["koide-real-pilot-plan"],
        help="write a blocked, digest-bound real Koide execution handoff; never executes Koide",
    )
    koide_real_plan.add_argument("--output", type=Path, required=True)
    koide_real_plan.add_argument("--camera-frame", default="camera0")
    koide_real_plan.add_argument("--lidar-frame", default="lidar0")
    koide_real_plan.add_argument("--json", action="store_true")
    koide_real_plan.set_defaults(func=_cmd_camera_lidar_koide_real_plan)
    koide_real_verify = camera_lidar_subcommands.add_parser(
        "koide-real-verify",
        aliases=["koide-real-pilot-verify"],
        help="verify external Koide evidence without executing Koide",
    )
    koide_real_verify.add_argument("request", type=Path)
    koide_real_verify.add_argument("--dataset", type=Path)
    koide_real_verify.add_argument("--archive", type=Path)
    koide_real_verify.add_argument("--input-manifest", type=Path)
    koide_real_verify.add_argument("--readiness", type=Path)
    koide_real_verify.add_argument("--config", type=Path)
    koide_real_verify.add_argument("--candidate", type=Path)
    koide_real_verify.add_argument("--external-run", type=Path)
    koide_real_verify.add_argument("--execution-log", type=Path)
    koide_real_verify.add_argument("--environment", type=Path)
    koide_real_verify.add_argument(
        "--evidence-label", choices=["official", "test"], default="official"
    )
    koide_real_verify.add_argument("--output", type=Path, required=True)
    koide_real_verify.add_argument("--json", action="store_true")
    koide_real_verify.set_defaults(func=_cmd_camera_lidar_koide_real_verify)
    koide_real_finalize = camera_lidar_subcommands.add_parser(
        "koide-real-finalize",
        aliases=["koide-real-pilot-finalize"],
        help="finalize a verified Koide output against the independent pilot",
    )
    koide_real_finalize.add_argument("request", type=Path)
    koide_real_finalize.add_argument("verification", type=Path)
    koide_real_finalize.add_argument("--pilot", type=Path)
    koide_real_finalize.add_argument("--evidence-label", choices=["official", "test"])
    koide_real_finalize.add_argument("--output", type=Path, required=True)
    koide_real_finalize.add_argument("--json", action="store_true")
    koide_real_finalize.set_defaults(func=_cmd_camera_lidar_koide_real_finalize)
    koide_export = camera_lidar_subcommands.add_parser(
        "export-koide-pilot",
        help="export only an admissible Koide pilot candidate to Autoware",
    )
    koide_export.add_argument("pilot", type=Path)
    koide_export.add_argument("--output", type=Path, required=True)
    koide_export.add_argument("--base-frame", required=True)
    koide_export.add_argument("--sensor-frame")
    koide_export.add_argument("--static-tf-output", type=Path)
    koide_export.add_argument("--manifest-output", type=Path)
    koide_export.add_argument("--force", action="store_true")
    koide_export.add_argument("--json", action="store_true")
    koide_export.set_defaults(func=_cmd_camera_lidar_export_koide_pilot)
    freeze_rotation = camera_lidar_subcommands.add_parser(
        "freeze-rotation-protocol",
        help="freeze the explicit Borer Fibonacci-sphere rotation protocol",
    )
    freeze_rotation.add_argument("problem", type=Path)
    freeze_rotation.add_argument("--output", type=Path, required=True)
    freeze_rotation.add_argument("--perturbation-count", type=_positive_int, default=200)
    freeze_rotation.add_argument("--rotation-deg", type=float, default=10.0)
    freeze_rotation.add_argument("--histogram-bins", type=_positive_int, default=32)
    freeze_rotation.add_argument("--min-visible-points", type=_positive_int, default=64)
    freeze_rotation.add_argument("--bound-deg", type=float, default=20.0)
    freeze_rotation.add_argument("--initial-step-deg", type=float, default=4.0)
    freeze_rotation.add_argument("--minimum-step-deg", type=float, default=0.05)
    freeze_rotation.add_argument("--max-evaluations", type=_positive_int, default=400)
    freeze_rotation.add_argument("--json", action="store_true")
    freeze_rotation.set_defaults(func=_cmd_camera_lidar_freeze_rotation_protocol)
    freeze_six_dof = camera_lidar_subcommands.add_parser(
        "freeze-six-dof-protocol",
        help="freeze paired rotation/translation Fibonacci perturbations",
    )
    freeze_six_dof.add_argument("problem", type=Path)
    freeze_six_dof.add_argument("--output", type=Path, required=True)
    freeze_six_dof.add_argument("--perturbation-count", type=_positive_int, default=200)
    freeze_six_dof.add_argument("--rotation-deg", type=float, default=0.5)
    freeze_six_dof.add_argument("--translation-m", type=float, default=0.5)
    freeze_six_dof.add_argument("--histogram-bins", type=_positive_int, default=32)
    freeze_six_dof.add_argument("--min-visible-points", type=_positive_int, default=64)
    freeze_six_dof.add_argument("--rotation-bound-deg", type=float, default=2.0)
    freeze_six_dof.add_argument("--translation-bound-m", type=float, default=1.0)
    freeze_six_dof.add_argument("--initial-rotation-step-deg", type=float, default=0.25)
    freeze_six_dof.add_argument("--initial-translation-step-m", type=float, default=0.10)
    freeze_six_dof.add_argument("--minimum-rotation-step-deg", type=float, default=0.01)
    freeze_six_dof.add_argument("--minimum-translation-step-m", type=float, default=0.005)
    freeze_six_dof.add_argument("--max-evaluations", type=_positive_int, default=800)
    freeze_six_dof.add_argument("--json", action="store_true")
    freeze_six_dof.set_defaults(func=_cmd_camera_lidar_freeze_six_dof_protocol)
    estimate_six_dof = camera_lidar_subcommands.add_parser(
        "estimate-six-dof",
        help="refine one D2D camera-LiDAR prior and save a standard calibration result",
    )
    estimate_six_dof.add_argument("problem", type=Path)
    estimate_six_dof.add_argument("--output", type=Path, required=True)
    estimate_six_dof.add_argument(
        "--frame-workers", type=int, default=1,
        help="persistent CPU frame threads with ordered reduction; CUDA requires 1",
    )
    estimate_six_dof.add_argument(
        "--projection-backend", choices=("numpy", "numba_cpu", "cuda"), default="numpy",
        help="D2D projection implementation (cuda requires calibrex[cuda])",
    )
    estimate_six_dof.add_argument(
        "--initial-result", type=Path,
        help="use the matching output transform from a previous standard result as the prior",
    )
    estimate_six_dof.add_argument(
        "--cuda-cache-mib", type=int,
        help="CUDA input cache capacity in MiB (default 256; 0 disables caching)",
    )
    estimate_six_dof.add_argument(
        "--holdout-frame-id", action="append", default=[],
        help="exclude this problem frame from optimization; repeat for multiple frames",
    )
    estimate_six_dof.add_argument("--histogram-bins", type=_positive_int, default=32)
    estimate_six_dof.add_argument("--min-visible-points", type=_positive_int, default=64)
    estimate_six_dof.add_argument("--rotation-bound-deg", type=_positive_float, default=2.0)
    estimate_six_dof.add_argument("--translation-bound-m", type=_positive_float, default=1.0)
    estimate_six_dof.add_argument("--initial-rotation-step-deg", type=_positive_float, default=0.25)
    estimate_six_dof.add_argument(
        "--initial-translation-step-m", type=_positive_float, default=0.10,
    )
    estimate_six_dof.add_argument("--minimum-rotation-step-deg", type=_positive_float, default=0.01)
    estimate_six_dof.add_argument(
        "--minimum-translation-step-m", type=_positive_float, default=0.005,
    )
    estimate_six_dof.add_argument("--max-evaluations", type=_positive_int, default=800)
    estimate_six_dof.add_argument("--improvement-tolerance", type=float, default=1.0e-9)
    estimate_six_dof.add_argument(
        "--objective", choices=("mutual_information", "normalized_mutual_information"),
        default="mutual_information",
    )
    estimate_six_dof.add_argument("--json", action="store_true")
    estimate_six_dof.set_defaults(func=_cmd_camera_lidar_estimate_six_dof)
    benchmark_rotation = camera_lidar_subcommands.add_parser(
        "benchmark-rotation",
        help="execute a frozen native D2D rotation recovery protocol",
    )
    benchmark_rotation.add_argument("problem", type=Path)
    benchmark_rotation.add_argument("protocol", type=Path)
    benchmark_rotation.add_argument("--trace-dir", type=Path, required=True)
    benchmark_rotation.add_argument("--definition-output", type=Path, required=True)
    benchmark_rotation.add_argument("--output", type=Path, required=True)
    benchmark_rotation.add_argument("--bullseye-output", type=Path)
    benchmark_rotation.add_argument("--bullseye-artifact-output", type=Path)
    benchmark_rotation.add_argument("--bootstrap-samples", type=_positive_int, default=2000)
    benchmark_rotation.add_argument("--workers", type=_positive_int, default=1)
    benchmark_rotation.add_argument(
        "--resume",
        action="store_true",
        help="reuse only digest-compatible completed traces in --trace-dir",
    )
    benchmark_rotation.add_argument("--required-hit-rate", type=float)
    benchmark_rotation.add_argument("--json", action="store_true")
    benchmark_rotation.set_defaults(func=_cmd_camera_lidar_benchmark_rotation)
    benchmark_six_dof = camera_lidar_subcommands.add_parser(
        "benchmark-six-dof",
        help="execute a frozen native D2D six-DoF recovery protocol",
    )
    benchmark_six_dof.add_argument("problem", type=Path)
    benchmark_six_dof.add_argument("protocol", type=Path)
    benchmark_six_dof.add_argument("--trace-dir", type=Path, required=True)
    benchmark_six_dof.add_argument("--definition-output", type=Path, required=True)
    benchmark_six_dof.add_argument("--output", type=Path, required=True)
    benchmark_six_dof.add_argument("--bootstrap-samples", type=_positive_int, default=2000)
    benchmark_six_dof.add_argument("--workers", type=_positive_int, default=1)
    benchmark_six_dof.add_argument(
        "--projection-backend",
        choices=("numpy", "numba_cpu", "cuda"),
        default="numpy",
        help="D2D projection implementation (cuda requires calibrex[cuda] and --workers 1)",
    )
    benchmark_six_dof.add_argument("--resume", action="store_true")
    benchmark_six_dof.add_argument(
        "--cuda-cache-mib", type=int,
        help="CUDA input cache capacity in MiB (default 256; 0 disables caching)",
    )
    benchmark_six_dof.add_argument("--required-hit-rate", type=float)
    benchmark_six_dof.add_argument("--json", action="store_true")
    benchmark_six_dof.set_defaults(func=_cmd_camera_lidar_benchmark_six_dof)
    probabilistic_pnp = camera_lidar_subcommands.add_parser(
        "refine-probabilistic-pnp",
        help="solve a schema-valid probabilistic 2D-3D correspondence frame",
    )
    probabilistic_pnp.add_argument("correspondence_artifact", type=Path)
    probabilistic_pnp.add_argument("frame_id")
    probabilistic_pnp.add_argument("--output", type=Path, required=True)
    probabilistic_pnp.add_argument("--result-id")
    probabilistic_pnp.add_argument(
        "--initial-problem",
        type=Path,
        help="camera-LiDAR problem whose D2D output/initial pose seeds PnP",
    )
    probabilistic_pnp.add_argument("--minimum-confidence", type=float, default=0.25)
    probabilistic_pnp.add_argument("--minimum-correspondences", type=_positive_int, default=6)
    probabilistic_pnp.add_argument("--ransac-reprojection-threshold-px", type=float, default=4.0)
    probabilistic_pnp.add_argument("--ransac-confidence", type=float, default=0.999)
    probabilistic_pnp.add_argument("--ransac-iterations", type=_positive_int, default=1000)
    probabilistic_pnp.add_argument("--mahalanobis-inlier-threshold", type=float, default=3.0)
    probabilistic_pnp.add_argument("--random-seed", type=int, default=0)
    probabilistic_pnp.add_argument("--json", action="store_true")
    probabilistic_pnp.set_defaults(func=_cmd_camera_lidar_refine_probabilistic_pnp)
    probabilistic_pnp_aggregate = camera_lidar_subcommands.add_parser(
        "refine-probabilistic-pnp-aggregate",
        help=(
            "solve one shared pose from reference-free confidence-supported probabilistic frames"
        ),
    )
    probabilistic_pnp_aggregate.add_argument("correspondence_artifact", type=Path)
    probabilistic_pnp_aggregate.add_argument("--output", type=Path, required=True)
    probabilistic_pnp_aggregate.add_argument("--result-id")
    probabilistic_pnp_aggregate.add_argument(
        "--initial-problem",
        type=Path,
        help="camera-LiDAR problem whose D2D output/initial pose seeds PnP",
    )
    probabilistic_pnp_aggregate.add_argument(
        "--initializer-calibration",
        type=Path,
        help="development lock supplying every aggregate PnP threshold",
    )
    probabilistic_pnp_aggregate.add_argument("--minimum-confidence", type=float, default=0.25)
    probabilistic_pnp_aggregate.add_argument(
        "--minimum-correspondences", type=_positive_int, default=6
    )
    probabilistic_pnp_aggregate.add_argument(
        "--minimum-frame-correspondences", type=_positive_int, default=4
    )
    probabilistic_pnp_aggregate.add_argument("--minimum-frames", type=_positive_int, default=2)
    probabilistic_pnp_aggregate.add_argument(
        "--ransac-reprojection-threshold-px", type=float, default=4.0
    )
    probabilistic_pnp_aggregate.add_argument("--ransac-confidence", type=float, default=0.999)
    probabilistic_pnp_aggregate.add_argument(
        "--ransac-iterations", type=_positive_int, default=1000
    )
    probabilistic_pnp_aggregate.add_argument(
        "--mahalanobis-inlier-threshold", type=float, default=3.0
    )
    probabilistic_pnp_aggregate.add_argument("--random-seed", type=int, default=0)
    probabilistic_pnp_aggregate.add_argument("--json", action="store_true")
    probabilistic_pnp_aggregate.set_defaults(
        func=_cmd_camera_lidar_refine_probabilistic_pnp_aggregate
    )
    probabilistic_multiframe = camera_lidar_subcommands.add_parser(
        "refine-probabilistic-multiframe",
        help="refine one shared D2D pose from all probabilistic frames",
    )
    probabilistic_multiframe.add_argument("correspondence_artifact", type=Path)
    probabilistic_multiframe.add_argument("initial_problem", type=Path)
    probabilistic_multiframe.add_argument(
        "--initial-trace",
        type=Path,
        help="schema-valid D2D candidate trace whose output pose initializes refinement",
    )
    probabilistic_multiframe.add_argument(
        "--confidence-calibration",
        type=Path,
        help="development lock that supplies every runtime refinement threshold",
    )
    probabilistic_multiframe.add_argument("--output", type=Path, required=True)
    probabilistic_multiframe.add_argument("--result-id")
    probabilistic_multiframe.add_argument("--minimum-confidence", type=float, default=0.25)
    probabilistic_multiframe.add_argument("--holdout-ratio", type=float, default=0.25)
    probabilistic_multiframe.add_argument("--split-seed", type=int, default=0)
    probabilistic_multiframe.add_argument(
        "--minimum-train-correspondences", type=_positive_int, default=24
    )
    probabilistic_multiframe.add_argument(
        "--minimum-holdout-correspondences", type=_positive_int, default=8
    )
    probabilistic_multiframe.add_argument("--max-evaluations", type=_positive_int, default=400)
    probabilistic_multiframe.add_argument(
        "--minimum-absolute-train-objective-improvement",
        type=float,
        default=1.0e-6,
    )
    probabilistic_multiframe.add_argument(
        "--minimum-relative-train-objective-improvement",
        type=float,
        default=1.0e-4,
    )
    probabilistic_multiframe.add_argument(
        "--maximum-train-correspondence-loss-fraction",
        type=float,
        default=0.05,
    )
    probabilistic_multiframe.add_argument(
        "--maximum-accepted-bound-fraction",
        type=float,
        default=0.95,
    )
    probabilistic_multiframe.add_argument("--without-covariance", action="store_true")
    probabilistic_multiframe.add_argument("--without-outlier-probability", action="store_true")
    probabilistic_multiframe.add_argument("--without-reliability", action="store_true")
    probabilistic_multiframe.add_argument("--json", action="store_true")
    probabilistic_multiframe.set_defaults(func=_cmd_camera_lidar_refine_probabilistic_multiframe)
    probabilistic_quality = camera_lidar_subcommands.add_parser(
        "diagnose-probabilistic-correspondence",
        help="write post-hoc frame support and six-DoF observability diagnostics",
    )
    probabilistic_quality.add_argument("correspondence_artifact", type=Path)
    probabilistic_quality.add_argument("refinement_result", type=Path)
    probabilistic_quality.add_argument("--output", type=Path, required=True)
    probabilistic_quality.add_argument("--report-id")
    probabilistic_quality.add_argument(
        "--pose-role",
        choices=["initializer", "candidate", "selected"],
        default="initializer",
    )
    probabilistic_quality.add_argument(
        "--minimum-frame-correspondences", type=_positive_int, default=4
    )
    probabilistic_quality.add_argument("--json", action="store_true")
    probabilistic_quality.set_defaults(func=_cmd_camera_lidar_diagnose_probabilistic_correspondence)
    probabilistic_confidence_calibration = camera_lidar_subcommands.add_parser(
        "calibrate-probabilistic-confidence",
        help="lock provider and refinement thresholds on a development split",
    )
    probabilistic_confidence_calibration.add_argument("correspondence_artifact", type=Path)
    probabilistic_confidence_calibration.add_argument("initial_problem", type=Path)
    probabilistic_confidence_calibration.add_argument("--output", type=Path, required=True)
    probabilistic_confidence_calibration.add_argument("--calibration-id")
    probabilistic_confidence_calibration.add_argument(
        "--thresholds",
        default=",".join(f"{value:g}" for value in confidence_thresholds),
        help="ascending comma-separated effective confidence thresholds",
    )
    probabilistic_confidence_calibration.add_argument(
        "--calibration-split-seeds", default="0,1,2,3,4,5,6,7,8,9"
    )
    probabilistic_confidence_calibration.add_argument(
        "--evaluation-split-seeds", default="0,1,2,3,4"
    )
    probabilistic_confidence_calibration.add_argument("--holdout-ratio", type=float, default=0.25)
    probabilistic_confidence_calibration.add_argument(
        "--minimum-train-correspondences", type=_positive_int, default=24
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-holdout-correspondences", type=_positive_int, default=8
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-frame-correspondences", type=_positive_int, default=4
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-frame-support-rate", type=float, default=0.95
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-full-rank-frame-rate", type=float, default=0.95
    )
    probabilistic_confidence_calibration.add_argument(
        "--development-reprojection-inlier-threshold-px",
        type=float,
        default=8.0,
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-geometric-inlier-rate", type=float, default=0.25
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-frame-geometric-inlier-count",
        type=_positive_int,
        default=4,
    )
    probabilistic_confidence_calibration.add_argument(
        "--minimum-frame-geometric-support-rate", type=float, default=0.95
    )
    probabilistic_confidence_calibration.add_argument(
        "--excluded-evaluation-dataset-ids",
        required=True,
        help="comma-separated evaluation dataset IDs that were not read",
    )
    probabilistic_confidence_calibration.add_argument("--json", action="store_true")
    probabilistic_confidence_calibration.set_defaults(
        func=_cmd_camera_lidar_calibrate_probabilistic_confidence
    )
    provider_support_comparison = camera_lidar_subcommands.add_parser(
        "compare-probabilistic-provider-support",
        help="compare like-for-like development provider support calibrations",
    )
    provider_support_comparison.add_argument("confidence_calibrations", type=Path, nargs="+")
    provider_support_comparison.add_argument("--output", type=Path, required=True)
    provider_support_comparison.add_argument("--comparison-id")
    provider_support_comparison.add_argument("--json", action="store_true")
    provider_support_comparison.set_defaults(
        func=_cmd_camera_lidar_compare_probabilistic_provider_support
    )
    probabilistic_initializer_calibration = camera_lidar_subcommands.add_parser(
        "calibrate-probabilistic-pnp-initializer",
        help="freeze aggregate PnP options on a development sequence",
    )
    probabilistic_initializer_calibration.add_argument("correspondence_artifact", type=Path)
    probabilistic_initializer_calibration.add_argument("initial_problem", type=Path)
    probabilistic_initializer_calibration.add_argument("--output", type=Path, required=True)
    probabilistic_initializer_calibration.add_argument("--calibration-id")
    probabilistic_initializer_calibration.add_argument(
        "--confidence-thresholds",
        default=",".join(f"{value:g}" for value in initializer_confidence),
    )
    probabilistic_initializer_calibration.add_argument(
        "--ransac-reprojection-thresholds-px",
        default=",".join(f"{value:g}" for value in initializer_ransac),
    )
    probabilistic_initializer_calibration.add_argument(
        "--random-seeds",
        default=",".join(str(value) for value in initializer_seeds),
    )
    probabilistic_initializer_calibration.add_argument(
        "--minimum-correspondences", type=_positive_int, default=4
    )
    probabilistic_initializer_calibration.add_argument(
        "--minimum-frame-correspondences", type=_positive_int, default=4
    )
    probabilistic_initializer_calibration.add_argument(
        "--minimum-frames", type=_positive_int, default=4
    )
    probabilistic_initializer_calibration.add_argument(
        "--ransac-confidence", type=float, default=0.999
    )
    probabilistic_initializer_calibration.add_argument(
        "--ransac-iterations", type=_positive_int, default=10000
    )
    probabilistic_initializer_calibration.add_argument(
        "--mahalanobis-inlier-threshold", type=float, default=3.0
    )
    probabilistic_initializer_calibration.add_argument(
        "--rotation-error-max-deg", type=float, default=0.5
    )
    probabilistic_initializer_calibration.add_argument(
        "--translation-error-max-m", type=float, default=0.20
    )
    probabilistic_initializer_calibration.add_argument(
        "--gate-minimum-selected-frame-count", type=_positive_int, default=4
    )
    probabilistic_initializer_calibration.add_argument(
        "--gate-minimum-selected-correspondence-count",
        type=_positive_int,
        default=16,
    )
    probabilistic_initializer_calibration.add_argument(
        "--gate-minimum-ransac-inlier-count", type=_positive_int, default=12
    )
    probabilistic_initializer_calibration.add_argument(
        "--gate-maximum-ransac-inlier-rmse-px", type=float, default=8.0
    )
    probabilistic_initializer_calibration.add_argument(
        "--gate-maximum-seed-rotation-delta-deg", type=float, default=0.01
    )
    probabilistic_initializer_calibration.add_argument(
        "--gate-maximum-seed-translation-delta-m", type=float, default=0.005
    )
    probabilistic_initializer_calibration.add_argument(
        "--excluded-evaluation-dataset-ids",
        required=True,
        help="comma-separated evaluation dataset IDs that were not read",
    )
    probabilistic_initializer_calibration.add_argument("--json", action="store_true")
    probabilistic_initializer_calibration.set_defaults(
        func=_cmd_camera_lidar_calibrate_probabilistic_pnp_initializer
    )
    probabilistic_ablation = camera_lidar_subcommands.add_parser(
        "benchmark-probabilistic-ablation",
        help="run paired covariance/outlier/reliability ablations",
    )
    probabilistic_ablation.add_argument("correspondence_artifact", type=Path)
    probabilistic_ablation.add_argument("initial_problem", type=Path)
    probabilistic_ablation.add_argument(
        "--initial-trace",
        type=Path,
        help="use one digest-pinned D2D output for every paired ablation",
    )
    probabilistic_ablation.add_argument("--result-dir", type=Path, required=True)
    probabilistic_ablation.add_argument("--definition-output", type=Path, required=True)
    probabilistic_ablation.add_argument("--output", type=Path, required=True)
    probabilistic_ablation.add_argument(
        "--split-seeds",
        default="0,1,2,3,4",
        help="comma-separated deterministic frame-split seeds",
    )
    probabilistic_ablation.add_argument("--bootstrap-samples", type=_positive_int, default=2000)
    probabilistic_ablation.add_argument("--json", action="store_true")
    probabilistic_ablation.set_defaults(func=_cmd_camera_lidar_benchmark_probabilistic_ablation)
    probabilistic_falsification = camera_lidar_subcommands.add_parser(
        "benchmark-probabilistic-falsification",
        help="run the integrated D2D-seeded six-DoF refinement falsification pack",
    )
    probabilistic_falsification.add_argument("correspondence_artifact", type=Path)
    probabilistic_falsification.add_argument("initial_problem", type=Path)
    probabilistic_trace_source = probabilistic_falsification.add_mutually_exclusive_group(
        required=True
    )
    probabilistic_trace_source.add_argument("--initial-trace", type=Path)
    probabilistic_trace_source.add_argument(
        "--trace-dir",
        type=Path,
        help=(
            "complete D2D trace directory with one <trial_id>.trace.yaml per protocol perturbation"
        ),
    )
    probabilistic_falsification.add_argument(
        "--protocol",
        type=Path,
        required=True,
        help="schema-valid fixed six-DoF D2D protocol for the initialization trace",
    )
    probabilistic_falsification.add_argument("--output-dir", type=Path, required=True)
    probabilistic_falsification.add_argument(
        "--split-seeds",
        default="0,1,2,3,4",
        help="comma-separated deterministic frame-split seeds",
    )
    probabilistic_falsification.add_argument("--known-bad-rotation-deg", type=float, default=5.0)
    probabilistic_falsification.add_argument("--known-bad-translation-m", type=float, default=0.5)
    probabilistic_falsification.add_argument(
        "--known-bad-min-holdout-rmse-delta-px", type=float, default=0.5
    )
    probabilistic_falsification.add_argument("--max-final-holdout-rmse-px", type=float)
    probabilistic_falsification.add_argument(
        "--bootstrap-samples", type=_positive_int, default=2000
    )
    probabilistic_falsification.add_argument("--json", action="store_true")
    probabilistic_falsification.set_defaults(
        func=_cmd_camera_lidar_benchmark_probabilistic_falsification
    )
    continuous_time = camera_lidar_subcommands.add_parser(
        "refine-continuous-time",
        help="jointly refine extrinsic and clock offset from a frozen problem",
    )
    continuous_time.add_argument("problem", type=Path)
    continuous_time.add_argument("--output", type=Path, required=True)
    continuous_time.add_argument("--result-id")
    continuous_time.add_argument("--json", action="store_true")
    continuous_time.set_defaults(func=_cmd_camera_lidar_refine_continuous_time)
    attach_continuous_trajectory = camera_lidar_subcommands.add_parser(
        "attach-continuous-trajectory",
        help="attach a recorded T_world_body trajectory to a frozen problem",
    )
    attach_continuous_trajectory.add_argument("problem", type=Path)
    attach_continuous_trajectory.add_argument("trajectory", type=Path)
    attach_continuous_trajectory.add_argument("--output", type=Path, required=True)
    attach_continuous_trajectory.add_argument("--problem-id")
    attach_continuous_trajectory.add_argument("--json", action="store_true")
    attach_continuous_trajectory.set_defaults(func=_cmd_camera_lidar_attach_continuous_trajectory)
    continuous_time_ablation = camera_lidar_subcommands.add_parser(
        "benchmark-continuous-time-ablation",
        help="run paired clock/per-point-time/covariance ablations",
    )
    continuous_time_ablation.add_argument("problem", type=Path)
    continuous_time_ablation.add_argument("--result-dir", type=Path, required=True)
    continuous_time_ablation.add_argument("--definition-output", type=Path, required=True)
    continuous_time_ablation.add_argument("--output", type=Path, required=True)
    continuous_time_ablation.add_argument("--split-seeds", default="0,1,2,3,4")
    continuous_time_ablation.add_argument("--bootstrap-samples", type=_positive_int, default=2000)
    continuous_time_ablation.add_argument("--json", action="store_true")
    continuous_time_ablation.set_defaults(func=_cmd_camera_lidar_benchmark_continuous_time_ablation)
    sota_audit = camera_lidar_subcommands.add_parser(
        "audit-sota",
        help="evaluate a digest-frozen Camera-LiDAR SOTA claim protocol",
    )
    sota_audit.add_argument("protocol", type=Path)
    sota_audit.add_argument("--output", type=Path, required=True)
    sota_audit.add_argument("--audit-id")
    sota_audit.add_argument("--json", action="store_true")
    sota_audit.set_defaults(func=_cmd_camera_lidar_audit_sota)
    baseline_audit = camera_lidar_subcommands.add_parser(
        "audit-external-baselines",
        help="materialize Koide/UniCalib license and comparability readiness records",
    )
    baseline_audit.add_argument("problem", type=Path)
    baseline_audit.add_argument("protocol", type=Path)
    baseline_audit.add_argument("--output-dir", type=Path, required=True)
    baseline_audit.add_argument("--koide-source-commit", required=True)
    baseline_audit.add_argument("--unicalib-source-commit", required=True)
    baseline_audit.add_argument("--json", action="store_true")
    baseline_audit.set_defaults(func=_cmd_camera_lidar_audit_external_baselines)

    empirical_uncertainty = camera_lidar_subcommands.add_parser(
        "empirical-uncertainty",
        help="report empirical SE(3) coverage from block-resampled refits",
    )
    empirical_uncertainty.add_argument("correspondence", type=Path)
    empirical_uncertainty.add_argument("initial_problem", type=Path)
    empirical_uncertainty.add_argument(
        "--result-dir",
        type=Path,
        required=True,
        help="directory holding one schema-valid refit artifact per resample",
    )
    empirical_uncertainty.add_argument("--output", type=Path, required=True)
    empirical_uncertainty.add_argument("--uncertainty-id")
    empirical_uncertainty.add_argument(
        "--workers", type=_positive_int, default=1,
        help="independent refit processes (default 1); inherits BLAS thread settings",
    )
    empirical_uncertainty.add_argument(
        "--block-length",
        type=_positive_int,
        default=5,
        help="frames per contiguous temporal block (default 5)",
    )
    empirical_uncertainty.add_argument(
        "--target-coverage",
        type=_coverage_ratio,
        default=0.9,
        help="target interval coverage in (0, 1) (default 0.9)",
    )
    empirical_uncertainty.add_argument(
        "--resample-count",
        type=_positive_int,
        default=20,
        help="number of deterministic block subsamples (default 20)",
    )
    empirical_uncertainty.add_argument(
        "--seed",
        type=int,
        default=0,
        help="deterministic block-subsample seed (default 0)",
    )
    empirical_uncertainty.add_argument(
        "--fit-block-ratio",
        type=_fit_ratio,
        default=0.6,
        help="fraction of blocks used for fitting (default 0.6)",
    )
    empirical_uncertainty.add_argument(
        "--overconfidence-scale",
        type=_overconfidence_scale,
        default=0.1,
        help="interval scale tested by the overconfidence control (default 0.1)",
    )
    empirical_uncertainty.add_argument(
        "--stability-only",
        action="store_true",
        help="report the empirical spread without a coverage claim",
    )
    empirical_uncertainty.add_argument("--json", action="store_true")
    empirical_uncertainty.set_defaults(func=_cmd_camera_lidar_empirical_uncertainty)

    external_run = subcommands.add_parser(
        "external-run",
        help="import or inspect external calibration run artifacts",
    )
    external_run_subcommands = external_run.add_subparsers(
        dest="external_run_command",
        required=True,
    )
    kalibr_import = external_run_subcommands.add_parser(
        "import-kalibr",
        help="import a Kalibr camchain YAML as a generic external-run artifact",
    )
    kalibr_import.add_argument("source", type=Path)
    kalibr_import.add_argument("--output", type=Path, required=True)
    kalibr_import.add_argument(
        "--input-artifact",
        type=Path,
        action="append",
        default=[],
        help="digest-bound Kalibr fitting input; may be repeated",
    )
    kalibr_import.add_argument("--expected-source-sha256")
    kalibr_import.add_argument("--tool-version")
    kalibr_import.add_argument("--source-commit")
    kalibr_import.add_argument(
        "--license-spdx",
        default="BSD-4-Clause",
        help="SPDX ID for the imported tool, or 'unknown'",
    )
    kalibr_import.add_argument("--training-isolation-declared", action="store_true")
    kalibr_import.add_argument("--training-isolation-evidence")
    kalibr_import.add_argument("--json", action="store_true")
    kalibr_import.set_defaults(func=_cmd_external_run_import_kalibr)
    tas_import = external_run_subcommands.add_parser(
        "import-sensor-calib-tas",
        help=(
            "import a sensor_calib_tas result (a bag with its *_calibrated tf_static, or "
            "an echoed ~/sensor_poses YAML) as a slac.check_frames file for calibrex check --tf"
        ),
    )
    tas_import.add_argument("source", type=Path)
    tas_import.add_argument("--output", type=Path, required=True)
    tas_import.add_argument("--tool-version")
    tas_import.add_argument("--json", action="store_true")
    tas_import.set_defaults(func=_cmd_external_run_import_sensor_calib_tas)

    camera_imu_evidence = external_run_subcommands.add_parser(
        "evaluate-camera-imu",
        help=(
            "evaluate an imported T_cam_imu/timeshift on a separate recording "
            "with temporal holdout and signed known-bad controls"
        ),
    )
    camera_imu_evidence.add_argument("external_run", type=Path)
    camera_imu_evidence.add_argument(
        "--recording",
        type=Path,
        required=True,
        help="slac.camera_imu_motion_recording/v0.1 not used for external fitting",
    )
    camera_imu_evidence.add_argument("--camera", default="cam0")
    camera_imu_evidence.add_argument("--output", type=Path, required=True)
    camera_imu_evidence.add_argument("--evaluation-id")
    camera_imu_evidence.add_argument("--json", action="store_true")
    camera_imu_evidence.set_defaults(func=_cmd_external_run_evaluate_camera_imu)

    camera_imu_fixture = external_run_subcommands.add_parser(
        "synthesize-camera-imu-fixture",
        help="write a nonphysical Kalibr camchain with separate fitting/evaluation recordings",
    )
    camera_imu_fixture.add_argument("--output-dir", type=Path, required=True)
    camera_imu_fixture.add_argument("--seed", type=int, default=20260927)
    camera_imu_fixture.add_argument(
        "--rotation-error-deg",
        type=float,
        nargs=3,
        default=(0.0, 0.0, 0.0),
        metavar=("X", "Y", "Z"),
        help="rotation-vector error composed onto the true T_cam_imu",
    )
    camera_imu_fixture.add_argument("--timeshift-error-sec", type=float, default=0.0)
    camera_imu_fixture.add_argument(
        "--translation-error-m",
        type=float,
        nargs=3,
        default=(0.0, 0.0, 0.0),
        metavar=("X", "Y", "Z"),
        help="error added to the camchain's T_cam_imu translation",
    )
    camera_imu_fixture.add_argument(
        "--no-accelerometer",
        action="store_true",
        help="omit camera positions and accelerometer samples (translation not evaluated)",
    )
    camera_imu_fixture.add_argument("--motion", choices=("full", "yaw_only"), default="full")
    camera_imu_fixture.add_argument("--json", action="store_true")
    camera_imu_fixture.set_defaults(func=_cmd_external_run_synthesize_camera_imu_fixture)

    koide_import = external_run_subcommands.add_parser(
        "import-koide",
        help="import a Koide direct_visual_lidar_calibration calib.json result",
    )
    koide_import.add_argument("source", type=Path)
    koide_import.add_argument("--output", type=Path, required=True)
    koide_import.add_argument("--lidar-frame", required=True)
    koide_import.add_argument("--camera-frame", required=True)
    koide_import.add_argument(
        "--input-artifact",
        type=Path,
        action="append",
        default=[],
        help="digest-bound Koide fitting input; may be repeated",
    )
    koide_import.add_argument("--expected-source-sha256")
    koide_import.add_argument("--tool-version")
    koide_import.add_argument("--source-commit")
    koide_import.add_argument(
        "--license-spdx",
        default="MIT",
        help="SPDX ID for the imported tool, or 'unknown'",
    )
    koide_import.add_argument("--training-isolation-declared", action="store_true")
    koide_import.add_argument("--training-isolation-evidence")
    koide_import.add_argument("--training-data-ids-sha256")
    koide_import.add_argument("--holdout-data-ids-sha256")
    koide_import.add_argument("--json", action="store_true")
    koide_import.set_defaults(func=_cmd_external_run_import_koide)

    koide_run = external_run_subcommands.add_parser(
        "run-koide",
        help="run the typed Koide preprocess/initial_guess/calibrate workflow from a config",
    )
    koide_run.add_argument("config", type=Path)
    koide_run.add_argument("--output", type=Path, required=True)
    koide_run.add_argument("--input-artifact", type=Path, action="append", default=[])
    koide_run.add_argument("--json", action="store_true")
    koide_run.set_defaults(func=_cmd_external_run_koide)

    trajectory = subcommands.add_parser(
        "trajectory",
        help="schema-valid continuous-time trajectory utilities",
    )
    trajectory_subcommands = trajectory.add_subparsers(
        dest="trajectory_command",
        required=True,
    )
    trajectory_build = trajectory_subcommands.add_parser(
        "build-contract",
        help="build a trajectory contract from a simple knots YAML",
    )
    trajectory_build.add_argument("knots_yaml", type=Path)
    trajectory_build.add_argument("--output", type=Path, required=True)
    trajectory_build.add_argument("--trajectory-id", required=True)
    trajectory_build.add_argument("--world-frame", default="map")
    trajectory_build.add_argument("--body-frame", default="base")
    trajectory_build.add_argument(
        "--interpolation",
        choices=["piecewise_linear_slerp/v0.1", "screw_linear/v0.1"],
        default="screw_linear/v0.1",
    )
    trajectory_build.add_argument("--json", action="store_true")
    trajectory_build.set_defaults(func=_cmd_trajectory_build_contract)
    trajectory_fit = trajectory_subcommands.add_parser(
        "fit",
        help="fit trajectory knots against point/pose measurements",
    )
    trajectory_fit.add_argument("trajectory", type=Path)
    trajectory_fit.add_argument("measurements", type=Path)
    trajectory_fit.add_argument("--output", type=Path, required=True)
    trajectory_fit.add_argument("--fit-id")
    trajectory_fit.add_argument("--max-iterations", type=_positive_int, default=30)
    trajectory_fit.add_argument("--initial-damping", type=float, default=1.0e-3)
    trajectory_fit.add_argument("--json", action="store_true")
    trajectory_fit.set_defaults(func=_cmd_trajectory_fit)
    trajectory_p2p = trajectory_subcommands.add_parser(
        "recover-point-to-plane",
        help="synthetic LiDAR point-to-plane recovery with holdout and known-bad",
    )
    trajectory_p2p.add_argument("--output", type=Path, required=True)
    trajectory_p2p.add_argument("--seed", type=int, default=20260820)
    trajectory_p2p.add_argument("--recovery-id", default="ct-lidar-p2p-synthetic")
    trajectory_p2p.add_argument("--json", action="store_true")
    trajectory_p2p.set_defaults(func=_cmd_trajectory_recover_point_to_plane)
    trajectory_imu = trajectory_subcommands.add_parser(
        "recover-imu-preintegration",
        help="synthetic IMU gyro pre-integration recovery with holdout and known-bad",
    )
    trajectory_imu.add_argument("--output", type=Path, required=True)
    trajectory_imu.add_argument("--seed", type=int, default=20260820)
    trajectory_imu.add_argument("--recovery-id", default="ct-imu-preintegration-synthetic")
    trajectory_imu.add_argument("--json", action="store_true")
    trajectory_imu.set_defaults(func=_cmd_trajectory_recover_imu_preintegration)
    trajectory_lever = trajectory_subcommands.add_parser(
        "recover-imu-lever-arm",
        help="synthetic IMU lever-arm recovery with holdout and known-bad",
    )
    trajectory_lever.add_argument("--output", type=Path, required=True)
    trajectory_lever.add_argument("--seed", type=int, default=20260820)
    trajectory_lever.add_argument("--recovery-id", default="ct-imu-lever-arm-synthetic")
    trajectory_lever.add_argument("--json", action="store_true")
    trajectory_lever.set_defaults(func=_cmd_trajectory_recover_imu_lever_arm)
    trajectory_clock = trajectory_subcommands.add_parser(
        "recover-imu-clock-offset",
        help="synthetic IMU clock-offset recovery with holdout and known-bad",
    )
    trajectory_clock.add_argument("--output", type=Path, required=True)
    trajectory_clock.add_argument("--seed", type=int, default=20260820)
    trajectory_clock.add_argument("--recovery-id", default="ct-imu-clock-offset-synthetic")
    trajectory_clock.add_argument("--json", action="store_true")
    trajectory_clock.set_defaults(func=_cmd_trajectory_recover_imu_clock_offset)
    trajectory_accel = trajectory_subcommands.add_parser(
        "recover-imu-accel-bias",
        help="synthetic IMU accelerometer-bias and gravity recovery",
    )
    trajectory_accel.add_argument("--output", type=Path, required=True)
    trajectory_accel.add_argument("--seed", type=int, default=20260820)
    trajectory_accel.add_argument("--recovery-id", default="ct-imu-accel-bias-synthetic")
    trajectory_accel.add_argument("--json", action="store_true")
    trajectory_accel.set_defaults(func=_cmd_trajectory_recover_imu_accel_bias)
    trajectory_intrinsics = trajectory_subcommands.add_parser(
        "recover-imu-intrinsics",
        help="synthetic IMU diagonal scale intrinsics recovery",
    )
    trajectory_intrinsics.add_argument("--output", type=Path, required=True)
    trajectory_intrinsics.add_argument("--seed", type=int, default=20260820)
    trajectory_intrinsics.add_argument("--recovery-id", default="ct-imu-intrinsics-synthetic")
    trajectory_intrinsics.add_argument("--json", action="store_true")
    trajectory_intrinsics.set_defaults(func=_cmd_trajectory_recover_imu_intrinsics)
    trajectory_joint = trajectory_subcommands.add_parser(
        "recover-lidar-imu-joint",
        help=(
            "synthetic joint LiDAR-IMU recovery: IMU rotation, gyro bias, lever arm, "
            "clock offset, accel bias and gravity with controls and separability"
        ),
    )
    trajectory_joint.add_argument("--output", type=Path, required=True)
    trajectory_joint.add_argument("--seed", type=int, default=20261010)
    trajectory_joint.add_argument("--recovery-id", default="ct-lidar-imu-joint-synthetic")
    trajectory_joint.add_argument(
        "--trajectory",
        choices=("screw_linear", "cubic_bspline"),
        default="screw_linear",
        help="trajectory model: screw-linear knots or a C2 cubic B-spline",
    )
    trajectory_joint.add_argument("--json", action="store_true")
    trajectory_joint.set_defaults(func=_cmd_trajectory_recover_lidar_imu_joint)
    trajectory_window = trajectory_subcommands.add_parser(
        "recover-sliding-window",
        help="synthetic sliding-window marginalization recovery",
    )
    trajectory_window.add_argument("--output", type=Path, required=True)
    trajectory_window.add_argument("--seed", type=int, default=20260820)
    trajectory_window.add_argument("--recovery-id", default="ct-sliding-window-synthetic")
    trajectory_window.add_argument("--json", action="store_true")
    trajectory_window.set_defaults(func=_cmd_trajectory_recover_sliding_window)

    lifecycle = subcommands.add_parser(
        "lifecycle",
        help="calibration lifecycle adoption and rollback evidence",
    )
    lifecycle_subcommands = lifecycle.add_subparsers(dest="lifecycle_command")
    lifecycle_subcommands.required = True
    lifecycle_simulate = lifecycle_subcommands.add_parser(
        "simulate",
        help="synthetic lifecycle replay with weak-observability and rollback controls",
    )
    lifecycle_simulate.add_argument("--output", type=Path, required=True)
    lifecycle_simulate.add_argument("--seed", type=int, default=20260820)
    lifecycle_simulate.add_argument("--lifecycle-id", default="calibration-lifecycle-synthetic")
    lifecycle_simulate.add_argument("--json", action="store_true")
    lifecycle_simulate.set_defaults(func=_cmd_lifecycle_simulate)

    lifecycle_init = lifecycle_subcommands.add_parser(
        "init",
        help="create an empty append-only calibration lifecycle registry",
    )
    lifecycle_init.add_argument("--registry-root", type=Path, required=True)
    lifecycle_init.add_argument("--registry-id", default="calibrex-registry")
    lifecycle_init.add_argument("--operator", default="unknown")
    lifecycle_init.add_argument("--reason", default="initialize calibration lifecycle registry")
    lifecycle_init.add_argument("--timestamp")
    lifecycle_init.add_argument("--json", action="store_true")
    lifecycle_init.set_defaults(func=_cmd_lifecycle_init)

    lifecycle_register_sensor = lifecycle_subcommands.add_parser(
        "register-sensor",
        help="register a physical sensor and its stable vehicle/sensor-kit identity",
    )
    lifecycle_register_sensor.add_argument("--registry-root", type=Path, required=True)
    lifecycle_register_sensor.add_argument("--sensor-id", required=True)
    lifecycle_register_sensor.add_argument("--vehicle-id", required=True)
    lifecycle_register_sensor.add_argument("--sensor-kit-id", required=True)
    lifecycle_register_sensor.add_argument("--serial", required=True)
    lifecycle_register_sensor.add_argument("--model", required=True)
    lifecycle_register_sensor.add_argument("--firmware", required=True)
    lifecycle_register_sensor.add_argument("--mount", required=True)
    lifecycle_register_sensor.add_argument("--frame")
    lifecycle_register_sensor.add_argument("--install", action="store_true")
    lifecycle_register_sensor.add_argument("--operator", default="unknown")
    lifecycle_register_sensor.add_argument("--reason", default="register physical sensor")
    lifecycle_register_sensor.add_argument("--timestamp")
    lifecycle_register_sensor.add_argument("--json", action="store_true")
    lifecycle_register_sensor.set_defaults(func=_cmd_lifecycle_register_sensor)

    lifecycle_capture = lifecycle_subcommands.add_parser(
        "capture",
        help="append a digest-verified capture-manifest event",
    )
    lifecycle_capture.add_argument("--registry-root", type=Path, required=True)
    lifecycle_capture.add_argument("--capture-manifest", type=Path, required=True)
    lifecycle_capture.add_argument("--operator", default="unknown")
    lifecycle_capture.add_argument("--reason", default="record calibration capture")
    lifecycle_capture.add_argument("--timestamp")
    lifecycle_capture.add_argument("--json", action="store_true")
    lifecycle_capture.set_defaults(func=_cmd_lifecycle_capture)

    lifecycle_edge = lifecycle_subcommands.add_parser(
        "register-edge",
        help="register one calibration edge and optional incumbent artifacts",
    )
    lifecycle_edge.add_argument("--registry-root", type=Path, required=True)
    lifecycle_edge.add_argument("--edge-id", required=True)
    lifecycle_edge.add_argument("--vehicle-id", required=True)
    lifecycle_edge.add_argument("--sensor-kit-id", required=True)
    lifecycle_edge.add_argument("--parent-frame", required=True)
    lifecycle_edge.add_argument("--child-frame", required=True)
    lifecycle_edge.add_argument("--incumbent-transform", type=Path)
    lifecycle_edge.add_argument("--incumbent-result", type=Path)
    lifecycle_edge.add_argument("--operator", default="unknown")
    lifecycle_edge.add_argument("--reason", default="register calibration edge")
    lifecycle_edge.add_argument("--timestamp")
    lifecycle_edge.add_argument("--json", action="store_true")
    lifecycle_edge.set_defaults(func=_cmd_lifecycle_register_edge)

    lifecycle_evaluate = lifecycle_subcommands.add_parser(
        "evaluate",
        help="evaluate candidate/capture/evidence without changing incumbents",
    )
    lifecycle_evaluate.add_argument("--registry-root", type=Path, required=True)
    lifecycle_evaluate.add_argument("--edge-id", action="append", required=True)
    lifecycle_evaluate.add_argument("--capture-manifest", type=Path, required=True)
    lifecycle_evaluate.add_argument("--candidate-result", type=Path)
    lifecycle_evaluate.add_argument("--candidate-transform", type=Path)
    lifecycle_evaluate.add_argument("--candidate-pilot", type=Path)
    lifecycle_evaluate.add_argument("--evidence", type=Path)
    lifecycle_evaluate.add_argument("--assessment", type=Path)
    lifecycle_evaluate.add_argument("--promotion", type=Path)
    lifecycle_evaluate.add_argument("--smoke", type=Path)
    lifecycle_evaluate.add_argument("--policy", type=Path)
    lifecycle_evaluate.add_argument("--output", type=Path)
    lifecycle_evaluate.add_argument("--operator", default="unknown")
    lifecycle_evaluate.add_argument("--reason", default="evaluate calibration candidate")
    lifecycle_evaluate.add_argument("--timestamp")
    lifecycle_evaluate.add_argument("--json", action="store_true")
    lifecycle_evaluate.set_defaults(func=_cmd_lifecycle_evaluate)

    lifecycle_promote = lifecycle_subcommands.add_parser(
        "promote",
        help="promote a PASS/ADOPT evaluation for exactly the declared edges",
    )
    lifecycle_promote.add_argument("--registry-root", type=Path, required=True)
    lifecycle_promote.add_argument("--edge-id", action="append", required=True)
    lifecycle_promote.add_argument("--evaluation", type=Path)
    lifecycle_promote.add_argument("--promotion", type=Path)
    lifecycle_promote.add_argument("--smoke", type=Path)
    lifecycle_promote.add_argument("--operator", default="unknown")
    lifecycle_promote.add_argument("--reason", default="promote evaluated calibration candidate")
    lifecycle_promote.add_argument("--timestamp")
    lifecycle_promote.add_argument("--json", action="store_true")
    lifecycle_promote.set_defaults(func=_cmd_lifecycle_promote)

    lifecycle_rollback = lifecycle_subcommands.add_parser(
        "rollback",
        help="append a guarded rollback to a prior incumbent",
    )
    lifecycle_rollback.add_argument("--registry-root", type=Path, required=True)
    lifecycle_rollback.add_argument("--edge-id", required=True)
    lifecycle_rollback.add_argument("--target-sequence", type=int)
    lifecycle_rollback.add_argument("--target-event-sha256")
    lifecycle_rollback.add_argument("--promotion", type=Path)
    lifecycle_rollback.add_argument("--operator", default="unknown")
    lifecycle_rollback.add_argument(
        "--reason", default="rollback calibration edge to prior incumbent"
    )
    lifecycle_rollback.add_argument("--timestamp")
    lifecycle_rollback.add_argument("--json", action="store_true")
    lifecycle_rollback.set_defaults(func=_cmd_lifecycle_rollback)

    lifecycle_record_ci = lifecycle_subcommands.add_parser(
        "record-ci",
        help="record a calibrex ci decision for one edge: evaluate (and optionally promote) "
        "the candidate, or roll back an incumbent the decision fails",
    )
    lifecycle_record_ci.add_argument(
        "ci_decision", type=Path, help="calibration-ci.json written by calibrex ci"
    )
    lifecycle_record_ci.add_argument("--registry-root", type=Path, required=True)
    lifecycle_record_ci.add_argument("--edge-id", required=True)
    lifecycle_record_ci.add_argument("--capture-manifest", type=Path, required=True)
    lifecycle_record_ci.add_argument("--promotion", type=Path)
    lifecycle_record_ci.add_argument("--smoke", type=Path)
    lifecycle_record_ci.add_argument(
        "--promote",
        action="store_true",
        help="promote the candidate when the evaluation admits it (ADOPT)",
    )
    lifecycle_record_ci.add_argument(
        "--rollback-on-fail",
        action="store_true",
        help="roll the edge back when a failing decision is about its promoted incumbent",
    )
    lifecycle_record_ci.add_argument("--operator", default="unknown")
    lifecycle_record_ci.add_argument("--timestamp")
    lifecycle_record_ci.add_argument("--output", type=Path, help="write the decision record")
    lifecycle_record_ci.add_argument("--json", action="store_true")
    lifecycle_record_ci.set_defaults(func=_cmd_lifecycle_record_ci)

    lifecycle_verify = lifecycle_subcommands.add_parser(
        "verify",
        help="verify event hash chain, head, projection, and source digests",
    )
    lifecycle_verify.add_argument("--registry-root", type=Path, required=True)
    lifecycle_verify.add_argument("--no-verify-sources", action="store_true")
    lifecycle_verify.add_argument("--json", action="store_true")
    lifecycle_verify.set_defaults(func=_cmd_lifecycle_verify)

    lifecycle_status = lifecycle_subcommands.add_parser(
        "status",
        help="show the verified lifecycle registry status projection",
    )
    lifecycle_status.add_argument("--registry-root", type=Path, required=True)
    lifecycle_status.add_argument("--json", action="store_true")
    lifecycle_status.set_defaults(func=_cmd_lifecycle_status)

    visualize = subcommands.add_parser("visualize", help="render result visualizations")
    visualize.add_argument("result", type=Path)
    visualize.add_argument(
        "--reference-result",
        type=Path,
        help="overlay another result's transforms as reference extrinsics",
    )
    visualize.add_argument("--output-dir", type=Path)
    visualize.add_argument("--export-html", action="store_true")
    visualize.add_argument("--json", action="store_true")
    visualize.set_defaults(func=_cmd_visualize)

    capture = subcommands.add_parser(
        "capture",
        help="capture/session inventory and readiness evidence",
    )
    capture_subcommands = capture.add_subparsers(dest="capture_command")
    capture_subcommands.required = True
    capture_inspect = capture_subcommands.add_parser(
        "inspect",
        help="inspect a bag or plain-file source into a capture manifest",
    )
    capture_inspect.add_argument("path", type=Path)
    capture_inspect.add_argument(
        "--type",
        choices=["auto", "files", "filesystem", "rosbag1", "rosbag2", "mcap"],
        default="auto",
        help=(
            "source format; defaults to path-based inference. MCAP inspection "
            "also emits bounded official framing/CRC/link evidence"
        ),
    )
    capture_inspect.add_argument("--capture-id")
    capture_inspect.add_argument("--session-id")
    capture_inspect.add_argument("--vehicle-id")
    capture_inspect.add_argument("--sensor-kit-id")
    capture_inspect.add_argument(
        "--sensor",
        action="append",
        default=[],
        metavar="ID:TYPE[:SERIAL[:MODEL[:FIRMWARE[:MOUNT[:FRAME]]]]]]",
        help="sensor identity; may be repeated",
    )
    capture_inspect.add_argument(
        "--readiness-profile",
        choices=["strict", "declared"],
        default="strict",
        help=(
            "strict treats every discovered stream as required; declared uses "
            "--required-stream/--required-kind and explicit optional critical streams"
        ),
    )
    capture_inspect.add_argument(
        "--required-stream",
        action="append",
        default=[],
        help="stream ID required for calibration intake; may be repeated",
    )
    capture_inspect.add_argument(
        "--optional-stream",
        action="append",
        default=[],
        help="stream ID explicitly treated as non-gating; may be repeated",
    )
    capture_inspect.add_argument(
        "--required-kind",
        action="append",
        choices=[
            "image",
            "camera_info",
            "depth_image",
            "rgbd",
            "pointcloud",
            "imu",
            "radar",
            "odometry",
            "metadata",
            "trajectory",
            "file",
            "other",
        ],
        default=[],
        help="stream kind required for calibration intake; may be repeated",
    )
    capture_inspect.add_argument("--config", type=Path)
    capture_inspect.add_argument("--sample-limit", type=_positive_int, default=4)
    capture_inspect.add_argument("--output", type=Path)
    capture_inspect.add_argument("--json", action="store_true")
    capture_inspect.set_defaults(func=_cmd_capture_inspect)
    capture_verify = capture_subcommands.add_parser(
        "verify",
        help="verify a saved capture manifest and recompute declared input digests",
    )
    capture_verify.add_argument("manifest", type=Path)
    capture_verify.add_argument("--json", action="store_true")
    capture_verify.set_defaults(func=_cmd_capture_verify)

    autoware = subcommands.add_parser(
        "autoware",
        help="ROS-independent Autoware package adapters",
    )
    autoware_subcommands = autoware.add_subparsers(dest="autoware_command", required=True)
    promotion = autoware_subcommands.add_parser(
        "promotion",
        help="plan, verify, apply, or roll back a sensor-kit promotion",
    )
    promotion_subcommands = promotion.add_subparsers(dest="promotion_command", required=True)
    promotion_plan = promotion_subcommands.add_parser(
        "plan",
        help="inspect a package and generate a deterministic dry-run plan",
    )
    promotion_plan.add_argument("candidate", type=Path)
    promotion_plan.add_argument("--workspace-root", type=Path, required=True)
    promotion_plan.add_argument("--package-root", type=Path, required=True)
    promotion_plan.add_argument("--individual-params-root", type=Path)
    promotion_plan.add_argument("--sensor-kit-description-root", type=Path)
    promotion_plan.add_argument("--vehicle-id", required=True)
    promotion_plan.add_argument("--sensor-kit-id", required=True)
    promotion_plan.add_argument("--baseline-manifest-sha256")
    promotion_plan.add_argument("--base-frame", default="base_link")
    promotion_plan.add_argument("--sensor-kit-base-frame", default="sensor_kit_base_link")
    promotion_plan.add_argument("--allowed-frame", action="append", default=[])
    promotion_plan.add_argument("--allowed-topic", action="append", default=[])
    promotion_plan.add_argument("--allowed-file", action="append", default=[])
    promotion_plan.add_argument("--required-file", action="append", default=[])
    promotion_plan.add_argument("--allow-warnings", action="store_true")
    promotion_plan.add_argument(
        "--profile", choices=["production", "developer"], default="production"
    )
    promotion_plan.add_argument("--require-smoke-for-apply", action="store_true")
    promotion_plan.add_argument("--output", type=Path, required=True)
    promotion_plan.add_argument("--json", action="store_true")
    promotion_plan.set_defaults(func=_cmd_autoware_promotion_plan)

    promotion_verify = promotion_subcommands.add_parser(
        "verify",
        help="re-read a plan's package and candidate without writing source files",
    )
    promotion_verify.add_argument("plan", type=Path)
    promotion_verify.add_argument("--output", type=Path)
    promotion_verify.add_argument("--json", action="store_true")
    promotion_verify.set_defaults(func=_cmd_autoware_promotion_verify)

    promotion_apply = promotion_subcommands.add_parser(
        "apply",
        help="atomically apply an admissible PASS/ADOPT plan",
    )
    promotion_apply.add_argument("plan", type=Path)
    promotion_apply.add_argument(
        "--smoke-artifact",
        type=Path,
        help="digest-bound PASS smoke artifact required for production plans",
    )
    promotion_apply.add_argument("--output", type=Path)
    promotion_apply.add_argument("--json", action="store_true")
    promotion_apply.set_defaults(func=_cmd_autoware_promotion_apply)

    promotion_rollback = promotion_subcommands.add_parser(
        "rollback",
        help="restore the exact files recorded by an applied promotion",
    )
    promotion_rollback.add_argument("plan", type=Path)
    promotion_rollback.add_argument("--output", type=Path)
    promotion_rollback.add_argument("--json", action="store_true")
    promotion_rollback.set_defaults(func=_cmd_autoware_promotion_rollback)

    smoke = autoware_subcommands.add_parser(
        "smoke",
        help="run, import, or verify downstream Autoware smoke evidence",
    )
    smoke_subcommands = smoke.add_subparsers(dest="smoke_command", required=True)
    smoke_run = smoke_subcommands.add_parser("run", help="run argv-only smoke stages")
    smoke_run.add_argument("plan", type=Path)
    smoke_run.add_argument(
        "--mode",
        choices=["subprocess", "container", "precomputed"],
        default="subprocess",
    )
    smoke_run.add_argument("--profile", choices=["production", "developer"], default="production")
    smoke_run.add_argument(
        "--stage-command",
        action="append",
        default=[],
        metavar="STAGE=JSON_ARGV",
        help='stage command, e.g. xacro_urdf=["python","-c","pass"] (repeatable)',
    )
    smoke_run.add_argument("--precomputed", type=Path)
    smoke_run.add_argument("--container-digest")
    smoke_run.add_argument("--environment-digest")
    smoke_run.add_argument("--tool-digest")
    smoke_run.add_argument("--timeout", type=float, default=120.0)
    smoke_run.add_argument("--output", type=Path, required=True)
    smoke_run.add_argument("--json", action="store_true")
    smoke_run.set_defaults(func=_cmd_autoware_smoke_run)

    smoke_import = smoke_subcommands.add_parser(
        "import", help="import precomputed smoke evidence and bind it to a plan"
    )
    smoke_import.add_argument("artifact", type=Path)
    smoke_import.add_argument("--plan", type=Path, required=True)
    smoke_import.add_argument("--output", type=Path, required=True)
    smoke_import.add_argument("--json", action="store_true")
    smoke_import.set_defaults(func=_cmd_autoware_smoke_import)

    smoke_verify = smoke_subcommands.add_parser(
        "verify", help="verify smoke self-digest and exact plan binding"
    )
    smoke_verify.add_argument("artifact", type=Path)
    smoke_verify.add_argument("--plan", type=Path, required=True)
    smoke_verify.add_argument("--json", action="store_true")
    smoke_verify.set_defaults(func=_cmd_autoware_smoke_verify)

    check = subcommands.add_parser(
        "check",
        help="audit the calibration deployed on a robot against a bag",
        description=(
            "Read candidate extrinsics from the bag's /tf_static and/or --tf files, classify "
            "the bag's sensor topics, and list the sensor pairs that can be checked. With "
            "--plan that is all; without it the native estimator of imu-lidar, lidar-lidar, "
            "camera-imu, camera-lidar (targetless edge alignment; rotation only) and the GNSS "
            "pairs gnss-lidar (NavSatFix antenna lever arm) and "
            "gnss-imu (composed from gnss-lidar and imu-lidar) runs and the candidate is "
            "judged against it (pass / warn / fail / inconclusive per pair). With --vehicle-frame "
            "the ground-vehicle pairs lidar-vehicle, imu-vehicle, ins-lidar and "
            "lidar-wheel_odometry run too. Other pairs are reported as skipped."
        ),
    )
    check.add_argument(
        "bag", type=Path, help="rosbag2 directory, .db3 / .mcap file, or ROS 1 .bag"
    )
    check.add_argument(
        "--tf",
        type=Path,
        action="append",
        default=[],
        metavar="FILE",
        help="candidate calibration: URDF, slac.check_frames YAML, Kalibr camchain-imucam, "
        "RTK-SLAM calib.yaml, or Hilti sensors list; repeatable; overrides bag /tf_static "
        "for the same child frame",
    )
    check.add_argument(
        "--vehicle-frame",
        default=None,
        help="ground-vehicle frame (for example base_link); vehicle pairs assume "
        "non-holonomic motion and are skipped unless this is given",
    )
    check.add_argument(
        "--frame-map",
        action="append",
        default=[],
        metavar="TOPIC=FRAME",
        help="map a sensor topic to a tree frame; repeatable",
    )
    check.add_argument(
        "--topic-kind",
        action="append",
        default=[],
        metavar="TOPIC=wheel|ins",
        help="classify an odometry or twist topic as wheel odometry or an INS/GNSS solution "
        "when its name does not say; repeatable",
    )
    check.add_argument(
        "--plan",
        action="store_true",
        help="dry run: list the checkable pairs without running any estimator",
    )
    check.add_argument(
        "--pairs",
        default=None,
        metavar="PAIR[,PAIR]",
        help="run only these pairs, for example imu-lidar,camera-imu (default: every wired pair)",
    )
    check.add_argument(
        "--max-duration-s",
        type=_positive_float,
        default=None,
        metavar="S",
        help="analyse only the first S seconds of each sensor stream",
    )
    check.add_argument(
        "--gnss-max-duration-s",
        type=_positive_float,
        default=None,
        metavar="S",
        help="analyse the first S seconds for gnss-lidar (and so gnss-imu), instead of "
        "--max-duration-s: the antenna lever arm needs several minutes of RTK-fixed windows, "
        "more than imu-lidar",
    )
    check.add_argument(
        "--camera",
        default=None,
        metavar="TOPIC",
        help="check only this camera (image topic or frame name)",
    )
    check.add_argument(
        "--sigma-k",
        type=_positive_float,
        default=3.0,
        help="tolerance = max(K * std, floor); default 3",
    )
    check.add_argument(
        "--rotation-floor-deg",
        type=_positive_float,
        default=0.5,
        help="smallest rotation tolerance in degrees (default 0.5)",
    )
    check.add_argument(
        "--translation-floor-m",
        type=_positive_float,
        default=0.02,
        help="smallest translation tolerance in metres (default 0.02)",
    )
    check.add_argument(
        "--detection-probe-deg",
        type=_positive_float,
        default=1.0,
        help="rotation error used by the detection-power self-test (default 1)",
    )
    check.add_argument(
        "--focal-scale-floor",
        type=_positive_float,
        default=0.005,
        metavar="FRACTION",
        help="smallest camera-focal tolerance as a fraction of the deployed focal length "
        "(default 0.005 = 0.5 %%); the tolerance is max(K * std, floor)",
    )
    check.add_argument(
        "--no-imu-lidar-translation",
        action="store_true",
        help="skip the IMU-LiDAR lever-arm estimate (rotation only; faster)",
    )
    check.add_argument(
        "--imu-lidar-deskew",
        choices=["auto", "gyro", "none"],
        default="auto",
        help="imu-lidar deskew: auto (default) deskews with the cloud's per-point time field "
        "and treats clouds without one as rigid scans; none forces rigid scans (biased on "
        "fast rotation); gyro requires the field",
    )
    check.add_argument(
        "--lidar-lidar-deskew",
        choices=["auto", "constant_velocity", "none"],
        default="auto",
        help="lidar-lidar: auto (default) deskews the reference LiDAR's odometry with its "
        "per-point time field and treats a reference cloud without one as rigid scans; none "
        "forces rigid scans (biased at speed); constant_velocity requires the field",
    )
    check.add_argument(
        "--gnss-lidar-deskew",
        choices=["auto", "constant_velocity", "none"],
        default="auto",
        help="gnss-lidar: auto (default) deskews the LiDAR odometry with the cloud's "
        "per-point time field and treats clouds without one as rigid scans; none forces "
        "rigid scans (biased at speed); constant_velocity requires the field",
    )
    check.add_argument(
        "--camera-lidar-motion",
        choices=["auto", "none"],
        default="auto",
        help="camera-lidar: auto (default) moves LiDAR points to the image time with an "
        "odometry, twist or IMU topic connected to the LiDAR in the frame tree (each point by "
        "its own time when the cloud has a per-point time field); none keeps scans as recorded",
    )
    check.add_argument(
        "--camera-lidar-far-control-t",
        dest="camera_lidar_start_scan_min_control_t",
        type=_camera_lidar_far_control_t,
        default=None,
        metavar="T",
        help="experimental camera-lidar control margin for accepting a fit from a distant "
        "start (finite T >= 2.5 on every observed rotation axis; default: no extra margin)",
    )
    check.add_argument(
        "--rigid-scan-rotation-floor-deg",
        type=_positive_float,
        default=None,
        metavar="DEG",
        help="rotation floor for imu-lidar axes judged on rigid scans (default 1.5)",
    )
    check.add_argument(
        "--acceleration-unit",
        choices=["mps2", "g"],
        default="mps2",
        help="accelerometer unit of the IMU (only the IMU-LiDAR lever arm uses it)",
    )
    check.add_argument(
        "--cache-dir",
        type=Path,
        default=None,
        metavar="DIR",
        help="cache of estimator artifacts, reused when the same bag is checked again "
        "(default: $XDG_CACHE_HOME/calibrex/check, i.e. ~/.cache/calibrex/check)",
    )
    check.add_argument(
        "--no-cache",
        action="store_true",
        help="always recompute the estimators and do not write the estimator cache",
    )
    check.add_argument(
        "--scan-memory-mb",
        type=int,
        default=2048,
        metavar="MB",
        help="memory used to keep decoded LiDAR scans across the estimator's passes "
        "(0 re-reads the bag every pass; default 2048)",
    )
    check.add_argument(
        "--evidence-dir",
        type=Path,
        default=None,
        help="where the estimator artifacts are written "
        "(default: <output stem>_evidence next to --output, else ./calibrex_check_evidence)",
    )
    check.add_argument(
        "--fail-on",
        choices=["fail", "warn", "inconclusive", "never"],
        default="fail",
        help="exit with status 1 when the overall verdict is at least this bad (default fail)",
    )
    check.add_argument(
        "--write-frames-template",
        type=Path,
        metavar="FILE",
        help="write a starter slac.check_frames YAML naming the bag's sensor frames, with "
        "TODO placeholder transforms; --tf refuses it until you fill it in and change its "
        "schema_version to slac.check_frames/v0.1",
    )
    check.add_argument("--output", type=Path, help="write the slac.calibration_check artifact")
    check.add_argument(
        "--html",
        type=Path,
        help="also write a self-contained HTML report (evidence links are relative to it)",
    )
    check.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    check.add_argument(
        "--quiet",
        "-q",
        action="store_true",
        help="suppress the progress report on stderr (the result on stdout is unchanged)",
    )
    check.set_defaults(func=_cmd_check)
    group_arguments(check, CHECK_ARGUMENT_GROUPS, rest_title=CHECK_ADVANCED_TITLE)

    estimate = subcommands.add_parser(
        "estimate",
        help="estimate the calibration of a bag that has none, and export it",
        description=(
            "For a bag with no calibration yet: run the native estimators of calibrex check "
            "(imu-lidar, camera-imu, the GNSS pairs, and with --vehicle-frame the "
            "ground-vehicle pairs; lidar-lidar and camera-lidar need a rough --tf prior to start "
            "from) and "
            "keep their estimates, each axis with its standard deviation and whether the data "
            "observed it. Writes bag_estimate.json (slac.bag_estimate/v0.1) and, for the "
            "frames whose six axes are observed (or filled from a --tf prior and marked), a "
            "slac.check_frames YAML, ROS 2 static_transform_publisher commands, a launch file "
            "and URDF joints into --output. Verify the result on a different recording with "
            "calibrex check <other bag> --tf OUTPUT/frames.yaml."
        ),
    )
    for action in check._actions:
        if action.dest in _ESTIMATE_SHARED_DESTS:
            estimate._add_action(action)
    estimate.add_argument(
        "--tf",
        type=Path,
        action="append",
        default=[],
        metavar="FILE",
        help="rough prior (URDF, slac.check_frames YAML, Kalibr camchain, ...; repeatable): "
        "starts lidar-lidar registration and camera-lidar edge alignment and supplies the axes "
        "the data cannot observe, "
        "which the exported YAML then marks as NOT MEASURED",
    )
    estimate.add_argument(
        "--pairs",
        default=None,
        metavar="PAIR[,PAIR]",
        help="estimate only these pairs, for example imu-lidar,camera-imu (default: every "
        "pair with an estimator)",
    )
    estimate.add_argument(
        "--output",
        type=Path,
        required=True,
        metavar="DIR",
        help="directory for bag_estimate.json, frames.yaml, static_transforms.sh, "
        "static_transforms.launch.yaml, joints.urdf.xml and the evidence artifacts",
    )
    estimate.add_argument(
        "--html",
        type=Path,
        metavar="FILE",
        help="also write a self-contained HTML report of the estimate "
        "(file links are relative to it); calibrex render DIR/bag_estimate.json --format html "
        "renders it again later",
    )
    estimate.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    estimate.add_argument(
        "--quiet",
        "-q",
        action="store_true",
        help="suppress the progress report on stderr (the result on stdout is unchanged)",
    )
    estimate.set_defaults(func=_cmd_estimate)

    drift = subcommands.add_parser(
        "drift",
        help="detect whether a rig's calibration changed between recordings of it",
        description=(
            "Give two or more bags of the SAME rig, in recording order. Each is estimated "
            "with calibrex estimate (the estimator cache makes a re-run cheap) and every axis "
            "that the data observed in at least two bags is tested for consistency: pairwise "
            "differences against max(K * combined std, floor) and a chi-square homogeneity "
            "test. Verdict per pair: stable, drift (naming the deviating bag when three or "
            "more bags allow it) or inconclusive (no axis observed in two bags). Writes "
            "calibration_drift.json (slac.calibration_drift/v0.1) and each bag's "
            "bag_estimate.json under OUTPUT/<bag-name>/."
        ),
    )
    drift.add_argument(
        "bags",
        type=Path,
        nargs="+",
        metavar="BAG",
        help="two or more bags (rosbag2, MCAP or ROS 1 .bag)",
    )
    for action in check._actions:
        if action.dest in _ESTIMATE_SHARED_DESTS - {"bag"}:
            drift._add_action(action)
    drift.add_argument(
        "--tf",
        type=Path,
        action="append",
        default=[],
        metavar="FILE",
        help="rough prior (as for estimate; repeatable): starts lidar-lidar registration",
    )
    drift.add_argument(
        "--pairs",
        default=None,
        metavar="PAIR[,PAIR]",
        help="compare only these pairs, for example imu-lidar (default: every pair with an "
        "estimator)",
    )
    drift.add_argument(
        "--output",
        type=Path,
        required=True,
        metavar="DIR",
        help="directory for calibration_drift.json and one sub-directory per bag",
    )
    drift.add_argument(
        "--html", type=Path, metavar="FILE", help="write a self-contained HTML report"
    )
    drift.add_argument(
        "--sigma-k",
        type=float,
        default=3.0,
        help="tolerance = max(K * combined std, floor); default 3",
    )
    drift.add_argument(
        "--rotation-floor-deg",
        type=float,
        default=0.5,
        help="smallest rotation change that is flagged (default 0.5)",
    )
    drift.add_argument(
        "--rigid-scan-rotation-floor-deg",
        type=float,
        default=1.5,
        help="rotation floor for imu-lidar axes estimated on rigid scans (default 1.5)",
    )
    drift.add_argument(
        "--translation-floor-m",
        type=float,
        default=0.02,
        help="smallest translation change that is flagged (default 0.02)",
    )
    drift.add_argument(
        "--time-offset-floor-ms",
        type=float,
        default=None,
        help="smallest clock-offset change that is flagged, for every pair type "
        "(default: a per-pair-type floor, 2 ms)",
    )
    drift.add_argument(
        "--chi2-alpha",
        type=float,
        default=0.01,
        help="significance of the chi-square homogeneity test (default 0.01)",
    )
    drift.add_argument(
        "--fail-on",
        choices=["drift", "inconclusive", "never"],
        default="drift",
        help="exit with status 1 when the overall verdict is at least this bad (default drift)",
    )
    drift.add_argument("--json", action="store_true", help="emit machine-readable JSON")
    drift.add_argument(
        "--quiet",
        "-q",
        action="store_true",
        help="suppress the progress report on stderr (the result on stdout is unchanged)",
    )
    drift.set_defaults(func=_cmd_drift)

    inspect = subcommands.add_parser("inspect", help="inspect a dataset")
    inspect.add_argument("path", type=Path)
    inspect.add_argument(
        "--type",
        choices=[
            "a2d2-lidar",
            "a2d2_lidar",
            "filesystem",
            "kitti-raw",
            "kitti_raw",
            "livox-pcd",
            "livox_pcd",
            "mcap",
            "nuscenes",
            "rosbag1",
            "rosbag2",
            "tum-rgbd",
            "tum_rgbd",
        ],
        default="filesystem",
    )
    inspect.add_argument(
        "--sample-limit",
        type=_positive_int,
        help=(
            "override the number of frames/files sampled for public-dataset diagnostics "
            "(a2d2_lidar, livox_pcd, kitti_raw); defaults preserve today's behavior"
        ),
    )
    inspect.add_argument("--json", action="store_true")
    inspect.set_defaults(func=_cmd_inspect)

    export = subcommands.add_parser("export", help="export a result to another format")
    export.add_argument("result", type=Path)
    export.add_argument("--format", choices=["ros-tf", "autoware"], required=True)
    export.add_argument(
        "--kind",
        choices=["result", "continuous-time-lidar-pair"],
        default="result",
        help="input artifact kind; continuous-time exports its refined transform",
    )
    export.add_argument("--output", type=Path, required=True)
    export.add_argument(
        "--base-frame",
        help="explicit Autoware parent frame; required when transform parents are ambiguous",
    )
    export.add_argument(
        "--sensor-frame",
        dest="sensor_frames",
        action="append",
        default=[],
        help="sensor child frame to export; may be repeated",
    )
    export.add_argument(
        "--transform",
        dest="transform_names",
        action="append",
        default=[],
        help="exact source transform key to export; may be repeated",
    )
    export.add_argument(
        "--invert",
        dest="invert_transforms",
        action="append",
        default=[],
        help="exact source transform key to invert before export; may be repeated",
    )
    export.add_argument(
        "--static-tf-output",
        type=Path,
        help="ROS 2 static_transform_publisher launch snippet (default: output sibling)",
    )
    export.add_argument(
        "--manifest-output",
        type=Path,
        help="schema-valid provenance manifest (default: output sibling)",
    )
    export.add_argument(
        "--force",
        action="store_true",
        help="allow replacement of existing export outputs",
    )
    export.add_argument("--json", action="store_true", help="emit machine-readable summary")
    export.set_defaults(func=_cmd_export)

    return parser


def _cmd_doctor(args: argparse.Namespace) -> int:
    from calibrex.core.config import DatasetType
    from calibrex.core.io import write_mapping
    from calibrex.core.koide_readiness import evaluate_koide_readiness_from_config
    from calibrex.diagnostics import build_doctor_artifact

    if args.workflow == "koide":
        if args.config is None:
            _die("doctor --workflow koide requires --config CONFIG")
        koide_artifact = evaluate_koide_readiness_from_config(
            args.config,
            command=_doctor_command(args),
        )
        payload = koide_artifact.model_dump(mode="json", exclude_none=False)
        if args.output is not None:
            koide_artifact.save(args.output)
            payload = koide_artifact.with_artifact_digest().model_dump(
                mode="json", exclude_none=False
            )
        if args.json:
            _emit(payload, as_json=True)
        else:
            print(
                f"Koide readiness: {koide_artifact.status.upper()} "
                f"({koide_artifact.hardware_profile}); dataset={koide_artifact.dataset_path}"
            )
            for check in koide_artifact.checks:
                print(f"  {check.name}: {check.status} - {check.reason}")
            for recommendation in koide_artifact.recommendations:
                print(f"  next: {recommendation}")
            if args.output is not None:
                print(f"  artifact: {args.output}")
        return 1 if koide_artifact.status == "blocked" else 0
    explicit_type = None
    if args.path is not None and args.type != "auto":
        explicit_type = cast(DatasetType, str(args.type).replace("-", "_"))
    artifact = build_doctor_artifact(
        calibrex_version=__version__,
        command=_doctor_command(args),
        path=args.path,
        dataset_type=explicit_type,
        sample_limit=args.sample_limit,
    )
    payload = artifact.model_dump(mode="json")
    if args.output is not None:
        write_mapping(args.output, payload)
    if args.json:
        _emit(payload, as_json=True)
    else:
        print(f"Calibrex {artifact.environment.calibrex_version}")
        print(f"Python {artifact.environment.python_version}")
        for name, dependency in artifact.environment.dependencies.items():
            state = "ok" if dependency.available else "missing"
            optional = " (optional)" if dependency.optional else ""
            version = (
                f" ({dependency.version})" if dependency.available and dependency.version else ""
            )
            print(f"{name}: {state}{optional}{version}")
        isolation = artifact.environment.python_path
        if isolation is not None:
            print(f"Python path: {isolation.status}")
            for module_name, origin in isolation.shadowed_modules.items():
                print(f"  shadowed: {module_name} -> {origin}")
            for entry in isolation.ros_path_entries:
                print(f"  ros path: {entry}")
            for recommendation in isolation.recommendations:
                print(f"  recommendation: {recommendation}")
        if artifact.dataset is not None:
            print(f"Dataset: {artifact.dataset.dataset_type} ({artifact.status.upper()})")
            print(f"  path: {artifact.dataset.path}")
            if artifact.quality is not None:
                print(f"  degeneracy: {artifact.quality.degeneracy.grade.upper()}")
                for recommendation in artifact.quality.recommendations:
                    print(f"  recommendation: {recommendation}")
            for suggestion in artifact.workflow_suggestions:
                print(f"  workflow: {suggestion.workflow_id} ({suggestion.status})")
                print(f"  template: {suggestion.template_path}")
                if suggestion.next_command is not None:
                    print(f"  next:     {suggestion.next_command}")
    return 1 if artifact.status == "fail" else 0


def _doctor_command(args: argparse.Namespace) -> list[str]:
    command = ["calibrex", "doctor"]
    if args.workflow != "environment":
        command.extend(["--workflow", str(args.workflow)])
    if args.config is not None:
        command.extend(["--config", str(args.config)])
    if args.path is not None:
        command.append(str(args.path))
    if args.type != "auto":
        command.extend(["--type", str(args.type)])
    if args.sample_limit is not None:
        command.extend(["--sample-limit", str(args.sample_limit)])
    if args.output is not None:
        command.extend(["--output", str(args.output)])
    if args.json:
        command.append("--json")
    return command


def _cmd_schema(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.core.schema_registry import (
        SCHEMA_LEDGER_FILENAME,
        SchemaRegistryError,
        schema_entries,
        schema_entry,
        schema_ledger,
    )

    if args.kind == "all":
        if args.output is not None:
            _die("schema all does not support --output; use --output-dir")
        if args.output_dir is None:
            _die("schema all requires --output-dir")
        args.output_dir.mkdir(parents=True, exist_ok=True)
        for entry in schema_entries():
            write_mapping(args.output_dir / entry.filename, dict(entry.json_schema()))
        write_mapping(args.output_dir / SCHEMA_LEDGER_FILENAME, schema_ledger())
        return 0
    if args.output_dir is not None:
        _die("--output-dir is only valid with schema all")
    if args.kind == "ledger":
        schema = schema_ledger()
    else:
        try:
            schema = dict(schema_entry(args.kind).json_schema())
        except SchemaRegistryError as exc:
            _die(str(exc))
    if args.output:
        write_mapping(args.output, schema)
    else:
        print(json.dumps(schema, indent=2, sort_keys=True))
    return 0


def _cmd_validate(args: argparse.Namespace) -> int:
    from calibrex.core.validation import ValidationKind, validate_file

    try:
        report = validate_file(
            args.path,
            cast(ValidationKind, args.kind),
            verify_inputs=bool(args.verify_inputs),
        )
    except (OSError, ValueError) as exc:
        _die(str(exc))
    payload = report.model_dump(mode="json")
    if report.migrated_from:
        payload["migrated_from"] = report.migrated_from
    if report.kind == "result":
        payload.update(
            {
                "production_valid": report.production_valid,
                "admissibility": report.admissibility,
                "provenance_issues": report.provenance_issues,
            }
        )
    if report.input_verification is not None:
        payload["input_verification"] = report.input_verification.model_dump(
            mode="json",
            exclude_none=False,
        )
    _emit(payload, args.json)
    return 0 if report.valid else 1


def _cmd_benchmark(args: argparse.Namespace) -> int:
    from calibrex.core.benchmark import (
        aggregate_benchmark_definition,
        load_benchmark_definition,
        render_benchmark_markdown,
        update_benchmark_table_in_markdown,
    )
    from calibrex.core.io import write_text

    definition = load_benchmark_definition(args.definition)
    try:
        benchmark = aggregate_benchmark_definition(definition)
    except ValueError as exc:
        raise BenchmarkError(str(exc)) from exc
    benchmark.save(args.output)
    payload: dict[str, Any] = {
        "benchmark": str(args.output),
        "benchmark_id": benchmark.benchmark_id,
        "method_count": len(benchmark.methods),
        "split_count": len(benchmark.protocol.splits),
        "trial_count": len(benchmark.trials),
    }
    if args.markdown_output is not None:
        write_text(args.markdown_output, render_benchmark_markdown(benchmark))
        payload["markdown"] = str(args.markdown_output)
    updated_markdown: list[str] = []
    for markdown_path in args.update_markdown:
        update_benchmark_table_in_markdown(markdown_path, benchmark)
        updated_markdown.append(str(markdown_path))
    if updated_markdown:
        payload["updated_markdown"] = updated_markdown
    _emit(payload, args.json)
    return 0


def _cmd_calibration_ci(args: argparse.Namespace) -> int:
    from calibrex.calibration_ci import run_calibration_ci

    command = ["calibrex", "ci", str(args.candidate)]
    if args.baseline is not None:
        command.extend(["--baseline", str(args.baseline)])
    if args.policy is not None:
        command.extend(["--policy", str(args.policy)])
    command.extend(["--output-dir", str(args.output_dir)])
    if args.allow_incompatible_protocol:
        command.append("--allow-incompatible-protocol")
    if args.enforce:
        command.append("--enforce")
    if args.json:
        command.append("--json")
    artifact = run_calibration_ci(
        args.candidate,
        output_dir=args.output_dir,
        calibrex_version=__version__,
        command=command,
        baseline_path=args.baseline,
        policy_path=args.policy,
        enforce_protocol=not args.allow_incompatible_protocol,
    )
    payload = artifact.model_dump(mode="json", exclude_none=True)
    payload["ci_artifact"] = str(args.output_dir / "calibration-ci.json")
    _emit(payload, args.json)
    return 1 if args.enforce and artifact.status != "pass" else 0


def _cmd_replay_plan(args: argparse.Namespace) -> int:
    from calibrex.core.raw_replay import plan_raw_replay

    plan = plan_raw_replay(
        args.definition,
        output=args.output,
        command=["calibrex", "replay", "plan", str(args.definition), "--output", str(args.output)],
    )
    _emit({**plan.model_dump(mode="json", exclude_none=False), "plan": str(args.output)}, args.json)
    return 0 if plan.status == "PASS" else 1


def _cmd_replay_run(args: argparse.Namespace) -> int:
    from calibrex.core.raw_replay import run_field_replacement_pilot, run_raw_replay

    result = run_raw_replay(
        args.definition,
        output_directory=args.output_dir,
        command=[
            "calibrex",
            "replay",
            "run",
            str(args.definition),
            "--output-dir",
            str(args.output_dir),
        ],
    )
    payload: dict[str, Any] = {
        **result.model_dump(mode="json", exclude_none=False),
        "replay_result": str(args.output_dir / "replay-result.json"),
    }
    if args.field_replacement:
        pilot = run_field_replacement_pilot(
            args.definition,
            output_directory=args.output_dir,
            command=["calibrex", "replay", "field-replacement", str(args.definition)],
        )
        payload["field_replacement_pilot"] = pilot.model_dump(mode="json", exclude_none=False)
    _emit(payload, args.json)
    return 0 if result.status == "PASS" else 1


def _cmd_replay_verify(args: argparse.Namespace) -> int:
    from calibrex.core.raw_replay import verify_raw_replay

    result = verify_raw_replay(args.result, definition=args.definition)
    _emit(
        {
            "valid": True,
            "replay_id": result.replay_id,
            "status": result.status,
            "decision": result.decision,
            "artifact_sha256": result.artifact_sha256,
        },
        args.json,
    )
    return 0


def _cmd_replay_compare(args: argparse.Namespace) -> int:
    from calibrex.core.raw_replay import compare_raw_replays

    comparison = compare_raw_replays(args.left, args.right, output=args.output)
    _emit(
        {
            **comparison.model_dump(mode="json", exclude_none=False),
            "comparison": str(args.output),
        },
        args.json,
    )
    return 0 if comparison.status == "PASS" else 1


def _cmd_replay_field_replacement(args: argparse.Namespace) -> int:
    from calibrex.core.raw_replay import run_field_replacement_pilot

    pilot = run_field_replacement_pilot(
        args.definition,
        output_directory=args.output_dir,
        command=["calibrex", "replay", "field-replacement", str(args.definition)],
    )
    _emit(
        {
            **pilot.model_dump(mode="json", exclude_none=False),
            "pilot": str(args.output_dir / "field-replacement-pilot.json"),
        },
        args.json,
    )
    return 0 if pilot.status == "PASS" else 1


def _cmd_multi_lidar_service_plan(args: argparse.Namespace) -> int:
    from calibrex.core.multi_lidar_service import build_multi_lidar_service_plan

    command = [
        "calibrex",
        "multi-lidar-service",
        "plan",
        str(args.definition),
        "--output",
        str(args.output),
    ]
    plan = build_multi_lidar_service_plan(args.definition, output=args.output, command=command)
    _emit(
        {
            **plan.model_dump(mode="json", exclude_none=False),
            "plan": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_multi_lidar_service_evaluate(args: argparse.Namespace) -> int:
    from calibrex.core.multi_lidar_service import evaluate_multi_lidar_service

    command = [
        "calibrex",
        "multi-lidar-service",
        "evaluate",
        str(args.plan),
        "--output",
        str(args.output),
    ]
    if args.candidate_replay is not None:
        command.extend(["--candidate-replay", str(args.candidate_replay)])
    evaluation = evaluate_multi_lidar_service(
        args.plan,
        candidate_replay=args.candidate_replay,
        output=args.output,
        evaluation_id=args.evaluation_id,
        command=command,
    )
    _emit(
        {
            **evaluation.model_dump(mode="json", exclude_none=False),
            "evaluation": str(args.output),
        },
        args.json,
    )
    return 0 if evaluation.status == "READY" else 1


def _cmd_multi_lidar_service_verify(args: argparse.Namespace) -> int:
    from calibrex.core.multi_lidar_service import verify_multi_lidar_service

    verification = verify_multi_lidar_service(args.artifact, plan=args.plan)
    _emit(verification.model_dump(mode="json", exclude_none=False), args.json)
    return 0 if verification.valid else 1


def _cmd_camera_imu_service_plan(args: argparse.Namespace) -> int:
    from calibrex.core.camera_imu_service import build_camera_imu_service_plan

    command = [
        "calibrex",
        "camera-imu-service",
        "plan",
        str(args.definition),
        "--output",
        str(args.output),
    ]
    plan = build_camera_imu_service_plan(args.definition, output=args.output, command=command)
    _emit(
        {
            **plan.model_dump(mode="json", exclude_none=False),
            "plan": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_camera_imu_service_evaluate(args: argparse.Namespace) -> int:
    from calibrex.core.camera_imu_service import evaluate_camera_imu_service

    command = [
        "calibrex",
        "camera-imu-service",
        "evaluate",
        str(args.plan),
        "--output",
        str(args.output),
    ]
    if args.candidate_replay is not None:
        command.extend(["--candidate-replay", str(args.candidate_replay)])
    evaluation = evaluate_camera_imu_service(
        args.plan,
        candidate_replay=args.candidate_replay,
        output=args.output,
        evaluation_id=args.evaluation_id,
        command=command,
    )
    _emit(
        {
            **evaluation.model_dump(mode="json", exclude_none=False),
            "evaluation": str(args.output),
        },
        args.json,
    )
    return 0 if evaluation.status == "READY" else 1


def _cmd_camera_imu_service_verify(args: argparse.Namespace) -> int:
    from calibrex.core.camera_imu_service import verify_camera_imu_service

    verification = verify_camera_imu_service(args.artifact, plan=args.plan)
    _emit(verification.model_dump(mode="json", exclude_none=False), args.json)
    return 0 if verification.valid else 1


def _cmd_radar_service_plan(args: argparse.Namespace) -> int:
    from calibrex.core.radar_service import build_radar_service_plan

    command = [
        "calibrex",
        "radar-service",
        "plan",
        str(args.definition),
        "--output",
        str(args.output),
    ]
    plan = build_radar_service_plan(args.definition, output=args.output, command=command)
    _emit(
        {
            **plan.model_dump(mode="json", exclude_none=False),
            "plan": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_radar_service_evaluate(args: argparse.Namespace) -> int:
    from calibrex.core.radar_service import evaluate_radar_service

    command = [
        "calibrex",
        "radar-service",
        "evaluate",
        str(args.plan),
        "--output",
        str(args.output),
    ]
    if args.candidate_replay is not None:
        command.extend(["--candidate-replay", str(args.candidate_replay)])
    evaluation = evaluate_radar_service(
        args.plan,
        candidate_replay=args.candidate_replay,
        output=args.output,
        evaluation_id=args.evaluation_id,
        command=command,
    )
    _emit(
        {
            **evaluation.model_dump(mode="json", exclude_none=False),
            "evaluation": str(args.output),
        },
        args.json,
    )
    return 0 if evaluation.status == "READY" else 1


def _cmd_radar_service_verify(args: argparse.Namespace) -> int:
    from calibrex.core.radar_service import verify_radar_service

    verification = verify_radar_service(args.artifact, plan=args.plan)
    _emit(verification.model_dump(mode="json", exclude_none=False), args.json)
    return 0 if verification.valid else 1


def _cmd_verify(args: argparse.Namespace) -> int:
    from calibrex.core.evidence_bundle import (
        verify_evidence_bundle,
        verify_evidence_bundle_verification,
        write_evidence_bundle_verification,
    )
    from calibrex.core.io import read_mapping

    artifact = Path(args.artifact)
    artifact_payload = read_mapping(artifact)
    schema_version = artifact_payload.get("schema_version")
    source_bundle_path: Path | str = artifact
    if schema_version == "slac.evidence_bundle.verification/v0.1":
        source_bundle_ref = artifact_payload.get("source_bundle")
        if isinstance(source_bundle_ref, dict):
            source_bundle_path_value = source_bundle_ref.get("path")
            if isinstance(source_bundle_path_value, str):
                source_bundle_path = _resolve_related_artifact_path(
                    artifact.parent,
                    source_bundle_path_value,
                )
        report = verify_evidence_bundle_verification(
            artifact,
            require_raw_recomputed=args.require_raw_recomputed,
        )
    else:
        report = verify_evidence_bundle(
            artifact,
            require_raw_recomputed=args.require_raw_recomputed,
        )
    payload = report.model_dump(mode="json")
    if args.output:
        report = write_evidence_bundle_verification(
            args.output,
            report,
            source_bundle_path=source_bundle_path,
        )
        payload = report.model_dump(mode="json")
    if args.json:
        _emit(payload, True)
    else:
        _emit_verification(report)
    return 0 if report.valid else 1


def _resolve_related_artifact_path(base_dir: Path, path: str) -> Path:
    artifact_path = Path(path)
    if artifact_path.is_absolute():
        return artifact_path
    return base_dir / artifact_path


def _cmd_assess(args: argparse.Namespace) -> int:
    from calibrex.core.assessment import assess_evidence_file
    from calibrex.core.evidence_contract import PolicyArtifact
    from calibrex.core.io import read_mapping, write_mapping

    policy = None
    if args.policy is not None:
        policy_artifact = PolicyArtifact.model_validate(read_mapping(args.policy))
        policy = policy_artifact.policy
    assessment = assess_evidence_file(args.evidence, policy=policy)
    payload = assessment.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    cli_payload = {
        **payload,
        "enforced": args.enforce,
        "would_fail_enforcement": assessment.status != "pass",
    }
    _emit(cli_payload, args.json)
    return 1 if args.enforce and assessment.status != "pass" else 0


def _cmd_evidence(args: argparse.Namespace) -> int:
    from calibrex.core.result import load_result
    from calibrex.visualization.report import (
        evidence_artifact_from_result,
        write_evidence_artifact,
        write_evidence_contract_artifacts,
    )

    result = load_result(args.result)
    if args.sidecars_dir is None:
        evidence = write_evidence_artifact(result, args.output)
        contract_artifacts: dict[str, str] = {}
    else:
        contract_artifacts = write_evidence_contract_artifacts(
            result,
            evidence_path=args.output,
            output_dir=args.sidecars_dir,
        )
        evidence = evidence_artifact_from_result(result)
    payload: dict[str, Any] = {
        "status": "ok",
        "source_result": str(args.result),
        "evidence": str(args.output),
        "run_id": evidence.run.id,
        "metrics_origin": evidence.materialization.metrics_origin,
        "data_verified": evidence.materialization.data_verified,
        "protocol_count": len(evidence.protocols),
        "case_count": len(evidence.cases),
        "summary_count": len(evidence.summaries),
        "recomputed_metrics": False,
    }
    if args.sidecars_dir is not None:
        payload["sidecars_dir"] = str(args.sidecars_dir)
        payload["contract_artifacts"] = contract_artifacts
    _emit(payload, args.json)
    return 0


def _cmd_init(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.init_templates import (
        list_sensor_template_names,
        template_summary,
        write_sensor_template,
    )

    if args.list_templates:
        payload = {
            "templates": template_summary(),
            "canonical": list_sensor_template_names(),
        }
        if args.json:
            _emit(payload, True)
        else:
            for name in list_sensor_template_names():
                print(name)
        return 0
    if args.template:
        if args.output is None:
            _die("--output is required with --template")
        try:
            written = write_sensor_template(args.template, args.output)
        except CalibrexError as exc:
            _die(str(exc))
        payload = {
            "status": "ok",
            "template": args.template,
            "output": str(written),
        }
        if args.json:
            _emit(payload, True)
        else:
            print(f"wrote {written}")
        return 0
    if args.profile is None:
        _die("profile is required unless --template or --list-templates is used")
    if args.output is None:
        _die("--output is required")
    config = _starter_config(args.profile)
    write_mapping(args.output, config)
    print(f"wrote {args.output}")
    return 0


def _cmd_calibrate(args: argparse.Namespace) -> int:
    from calibrex.core.config import load_config
    from calibrex.data.inspect import inspect_dataset
    from calibrex.pipelines.calibrate import CalibrationRunOptions, run_calibration
    from calibrex.visualization.report import report_artifact_paths

    if args.online and args.candidate_extrinsics:
        _die(
            "--candidate-extrinsics is not supported with --online; "
            "run the offline `calibrex calibrate` to compare candidate extrinsics"
        )
    config = load_config(args.config)
    if args.online:
        return _cmd_calibrate_online(args, config)
    result = run_calibration(
        args.config,
        CalibrationRunOptions(
            dry_run=args.dry_run,
            output_dir=args.output_dir,
            strict=args.strict,
            seed=args.seed,
            candidate_extrinsics=tuple(args.candidate_extrinsics),
        ),
    )
    if args.dry_run:
        inspection = inspect_dataset(config.dataset)
        payload = {
            "status": "ok",
            "config": str(args.config),
            "dataset": inspection.as_dict(),
        }
        _emit(payload, args.json)
        return 0
    if result is None:
        _die("calibration did not produce a result")
    output_dir = args.output_dir or config.output_dir
    artifacts = report_artifact_paths(output_dir, html_filename=config.outputs.report)
    summary: dict[str, Any] = {
        "status": result.run.status,
        "grade": result.quality.grade,
        "run_id": result.run.id,
        "result": str(output_dir / config.outputs.result),
        "report": artifacts["html_report"],
        "report_artifacts": artifacts,
    }
    _emit(summary, args.json)
    return 1 if args.strict and result.quality.grade != "pass" else 0


def _cmd_calibrate_online(args: argparse.Namespace, config: CalibrationConfig) -> int:
    from calibrex.data.inspect import inspect_dataset
    from calibrex.pipelines.online import OnlineCalibrationRunOptions, run_online_calibration
    from calibrex.visualization.report import report_artifact_paths

    result = run_online_calibration(
        args.config,
        OnlineCalibrationRunOptions(
            dry_run=args.dry_run,
            output_dir=args.output_dir,
            strict=args.strict,
            seed=args.seed if args.seed is not None else 0,
            batch_size=args.batch_size,
            rolling_window=args.rolling_window,
            holdout_ratio=args.holdout_ratio,
            accumulation_batches=args.accumulation_batches,
            max_accumulated_train_points=args.max_accumulated_train_points,
        ),
    )
    if args.dry_run:
        inspection = inspect_dataset(config.dataset)
        payload = {
            "status": "ok",
            "config": str(args.config),
            "dataset": inspection.as_dict(),
        }
        _emit(payload, args.json)
        return 0
    if result is None:
        _die("online calibration did not produce a result")
    output_dir = args.output_dir or config.output_dir
    artifacts = report_artifact_paths(output_dir, html_filename=config.outputs.report)
    summary: dict[str, Any] = {
        "status": result.run.status,
        "grade": result.quality.grade,
        "run_id": result.run.id,
        "result": str(output_dir / config.outputs.result),
        "report": artifacts["html_report"],
        "report_artifacts": artifacts,
        "timeline": result.run.provenance.get("online_timeline_path"),
        "trajectory": result.run.provenance.get("trajectory_path"),
        "batch_count": result.run.provenance.get("online_batch_count"),
        "accepted_batch_count": result.run.provenance.get("online_accepted_batch_count"),
        "rejected_batch_count": result.run.provenance.get("online_rejected_batch_count"),
        "final_gate_status": result.run.provenance.get("online_final_gate_status"),
    }
    _emit(summary, args.json)
    return 1 if args.strict and result.quality.grade != "pass" else 0


def _cmd_compile(args: argparse.Namespace) -> int:
    from calibrex.core.config import load_config
    from calibrex.core.frames import FrameGraph
    from calibrex.core.io import write_mapping
    from calibrex.data.inspect import inspect_dataset
    from calibrex.graph.problem import build_problem

    config = load_config(args.config)
    inspection = inspect_dataset(config.dataset)
    problem = build_problem(config, FrameGraph.from_config(config), inspection)
    payload = problem.as_dict()
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not args.output:
        _emit(problem.summary(), as_json=False)
    return 0


def _cmd_evaluate(args: argparse.Namespace) -> int:
    from calibrex.core.result import load_result
    from calibrex.evaluation.evidence_summary import evidence_cases_from_result
    from calibrex.evaluation.metrics import evaluate_quality
    from calibrex.evaluation.thresholds import ThresholdProfile
    from calibrex.visualization.overlays import write_camera_lidar_overlay_artifact
    from calibrex.visualization.report import write_report_artifacts
    from calibrex.visualization.rig3d import write_rig_3d_artifact

    profile = cast(ThresholdProfile | None, args.threshold_profile)
    result = evaluate_quality(
        load_result(args.result),
        strict=args.strict,
        threshold_profile=profile,
    )
    if args.export_html:
        output_dir = args.output_dir or args.result.parent
        output_dir.mkdir(parents=True, exist_ok=True)
        write_camera_lidar_overlay_artifact(result, output_dir / "artifacts")
        write_rig_3d_artifact(result, output_dir / "artifacts")
        report_artifacts = write_report_artifacts(result, output_dir)
    else:
        report_artifacts = {}
    if args.output_dir:
        args.output_dir.mkdir(parents=True, exist_ok=True)
        output = args.output_dir / args.result.name
        result.save(output)
    payload = {
        "grade": result.quality.grade,
        "warnings": result.quality.warnings,
        "blocking_failures": result.quality.blocking_failures,
        "recommendation": result.quality.recommendation,
        "html_report": result.artifacts.html_report,
        "report_artifacts": report_artifacts,
        "metrics_origin": result.run.provenance.get("metrics_origin", "unknown"),
        "data_verified": result.run.provenance.get("data_verified"),
        "evidence_case_count": len(evidence_cases_from_result(result)),
    }
    warning = _report_materialization_warning(
        payload["metrics_origin"],
        payload["data_verified"],
        command="evaluate",
    )
    if warning is not None:
        payload["warning"] = warning
    _emit(payload, args.json)
    return 1 if result.quality.grade == "fail" else 0


def _render_check_artifact(args: argparse.Namespace) -> int | None:
    """Render a ``slac.calibration_check`` artifact; ``None`` when ``result`` is another kind."""
    from calibrex.core.calibration_check import (
        CALIBRATION_CHECK_SCHEMA_VERSION,
        CalibrationCheckArtifact,
    )
    from calibrex.core.io import read_mapping
    from calibrex.visualization.check_report import write_check_html

    try:
        payload = read_mapping(args.result)
    except Exception:
        return None
    if not isinstance(payload, dict) or payload.get("schema_version") != (
        CALIBRATION_CHECK_SCHEMA_VERSION
    ):
        return None
    if args.format != "html":
        _die("a calibration check artifact renders to --format html only")
    artifact = CalibrationCheckArtifact.model_validate(payload)
    target = args.html or args.result.with_suffix(".html")
    if not target.is_absolute() and target.parent == Path("."):
        target = (args.output_dir or args.result.parent) / target.name
    write_check_html(artifact, target, artifact_dir=args.result.parent)
    _emit(
        {
            "status": "ok",
            "command": "render",
            "render_only": True,
            "recomputed_metrics": False,
            "source_result": str(args.result),
            "output_format": "html",
            "html_report": str(target),
        },
        args.json,
    )
    return 0


def _render_estimate_artifact(args: argparse.Namespace) -> int | None:
    """Render a ``slac.bag_estimate`` artifact; ``None`` when ``result`` is another kind."""
    from calibrex.core.bag_estimate import BAG_ESTIMATE_SCHEMA_VERSION, BagEstimateArtifact
    from calibrex.core.io import read_mapping
    from calibrex.visualization.estimate_report import write_estimate_html

    try:
        payload = read_mapping(args.result)
    except Exception:
        return None
    if not isinstance(payload, dict) or payload.get("schema_version") != (
        BAG_ESTIMATE_SCHEMA_VERSION
    ):
        return None
    if args.format != "html":
        _die("a bag estimate artifact renders to --format html only")
    artifact = BagEstimateArtifact.model_validate(payload)
    target = args.html or args.result.with_suffix(".html")
    if not target.is_absolute() and target.parent == Path("."):
        target = (args.output_dir or args.result.parent) / target.name
    write_estimate_html(artifact, target, artifact_dir=args.result.parent)
    _emit(
        {
            "status": "ok",
            "command": "render",
            "render_only": True,
            "recomputed_metrics": False,
            "source_result": str(args.result),
            "output_format": "html",
            "html_report": str(target),
        },
        args.json,
    )
    return 0


def _cmd_render(args: argparse.Namespace) -> int:
    from calibrex.core.result import load_result
    from calibrex.visualization.evidence_card import write_evidence_card

    rendered = _render_check_artifact(args)
    if rendered is None:
        rendered = _render_estimate_artifact(args)
    if rendered is not None:
        return rendered
    if args.format == "evidence-card":
        if args.html is not None:
            _die("--html cannot be used with --format evidence-card")
        result = load_result(args.result)
        output_path = _evidence_card_output_path(args.result, args.output_dir, args.output)
        write_evidence_card(result, output_path, source_path=args.result)
        _emit(
            {
                "status": "ok",
                "command": "render",
                "render_only": True,
                "recomputed_metrics": False,
                "source_result": str(args.result),
                "output_format": "evidence-card",
                "evidence_card": str(output_path),
                "source_sha256_bound": True,
            },
            args.json,
        )
        return 0
    if args.output is not None:
        _die("--output is only supported with --format evidence-card")
    return _render_result_report(args, command="render", deprecated_alias=None)


def _cmd_report(args: argparse.Namespace) -> int:
    return _render_result_report(args, command="report", deprecated_alias="report")


def _render_result_report(
    args: argparse.Namespace,
    *,
    command: str,
    deprecated_alias: str | None,
) -> int:
    from calibrex.core.result import load_result
    from calibrex.evaluation.evidence_summary import evidence_cases_from_result
    from calibrex.visualization.report import write_report_artifacts

    result = load_result(args.result)
    output_dir = args.output_dir or _report_output_dir(args.result, args.html)
    html_filename = _report_html_filename(args.html)
    metrics_origin = result.run.provenance.get("metrics_origin", "unknown")
    data_verified = result.run.provenance.get("data_verified")
    report_artifacts = write_report_artifacts(
        result,
        output_dir,
        html_filename=html_filename,
    )
    payload = {
        "status": "ok",
        "command": command,
        "canonical_command": "render",
        "deprecated_alias": deprecated_alias,
        "render_only": True,
        "recomputed_metrics": False,
        "source_result": str(args.result),
        "output_format": "html",
        "html_report": report_artifacts["html_report"],
        "report_artifacts": report_artifacts,
        "metrics_origin": metrics_origin,
        "data_verified": data_verified,
        "evidence_case_count": len(evidence_cases_from_result(result)),
    }
    warning = _report_materialization_warning(metrics_origin, data_verified, command=command)
    if warning is not None:
        payload["warning"] = warning
    _emit(payload, args.json)
    return 0


def _report_materialization_warning(
    metrics_origin: object,
    data_verified: object,
    *,
    command: str,
) -> str | None:
    if metrics_origin == "cached" or data_verified is False:
        return f"cached evidence: raw data was not read or recomputed by this {command} command"
    return None


def _report_output_dir(result_path: Path, html_path: Path | None) -> Path:
    if html_path is not None and html_path.is_absolute():
        return html_path.parent
    if html_path is not None and html_path.parent != Path("."):
        return html_path.parent
    return result_path.parent


def _report_html_filename(html_path: Path | None) -> str | Path:
    if html_path is None:
        return "report.html"
    if html_path.is_absolute():
        return html_path
    return html_path.name


def _evidence_card_output_path(
    result_path: Path,
    output_dir: Path | None,
    output_path: Path | None,
) -> Path:
    if output_path is not None and (output_path.is_absolute() or output_path.parent != Path(".")):
        return output_path
    base = output_dir or result_path.parent
    if output_path is None:
        return base / "evidence-card.svg"
    return base / output_path


def _cmd_compare(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.core.result import load_result
    from calibrex.evaluation.compare import compare_results
    from calibrex.visualization.comparison_table import write_comparison_table

    left_result = load_result(args.left_result)
    right_result = load_result(args.right_result)
    comparison = compare_results(
        left_result,
        right_result,
        left_path=args.left_result,
        right_path=args.right_result,
    )
    if args.format == "evidence-table":
        output_path = args.output or Path("comparison-table.svg")
        write_comparison_table(
            left_result,
            right_result,
            output_path,
            left_path=args.left_result,
            right_path=args.right_result,
            left_label=args.left_label,
            right_label=args.right_label,
        )
        _emit(
            {
                "status": "ok",
                "command": "compare",
                "output_format": "evidence-table",
                "comparison_table": str(output_path),
                "left_source": str(args.left_result),
                "right_source": str(args.right_result),
                "source_sha256_bound": True,
                "protocol_compatibility": comparison.protocol_compatibility.status,
            },
            args.json,
        )
        if args.enforce_compatible and comparison.protocol_compatibility.status != "compatible":
            return 1
        return 0
    payload = comparison.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not args.output:
        _emit_comparison(
            comparison,
            enforce_compatible=args.enforce_compatible,
        )
    if args.enforce_compatible and comparison.protocol_compatibility.status != "compatible":
        return 1
    return 0


def _cmd_report_compare(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.core.result import load_result
    from calibrex.evaluation.report_compare import compare_reports

    labeled_paths = _parse_labeled_results(args.entries)
    labeled_results = [(label, load_result(path)) for label, path in labeled_paths]
    paths = {label: cast(Path | str | None, path) for label, path in labeled_paths}
    try:
        report = compare_reports(
            labeled_results,
            paths=paths,
            reference_label=args.reference,
        )
    except ValueError as exc:
        _die(str(exc))
    payload = report.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not args.output:
        _emit_report_comparison(report, enforce_compatible=args.enforce_compatible)
    if args.enforce_compatible and report.summary.protocol_compatibility_status != "compatible":
        return 1
    return 0


def _cmd_window_consistency(args: argparse.Namespace) -> int:
    from calibrex.core.dynamic_window import DynamicWindowConsistencyThresholds
    from calibrex.core.io import write_mapping
    from calibrex.core.result import load_result
    from calibrex.evaluation.dynamic_window import evaluate_dynamic_window_consistency

    labeled_paths = _parse_labeled_results(args.entries)
    labeled_results = [(label, load_result(path)) for label, path in labeled_paths]
    try:
        artifact = evaluate_dynamic_window_consistency(
            labeled_results,
            paths=dict(labeled_paths),
            transform_id=args.transform,
            thresholds=DynamicWindowConsistencyThresholds(
                max_translation_delta_m=args.max_translation_delta_m,
                max_rotation_delta_deg=args.max_rotation_delta_deg,
            ),
            reference_label=args.reference,
        )
    except ValueError as exc:
        _die(str(exc))
    payload = artifact.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not args.output:
        print(
            f"window consistency: {artifact.grade} "
            f"({len(artifact.blocking_failures)} blocking failures, "
            f"{len(artifact.warnings)} warnings)"
        )
    if args.enforce and artifact.grade != "pass":
        return 1
    return 0


def _cmd_trajectory_window_drift(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.pipelines.online import evaluate_rosbag2_trajectory_window_drift

    artifact = evaluate_rosbag2_trajectory_window_drift(
        args.config,
        reference_result_path=args.reference_result,
        use_point_time_offsets=(None if args.deskew == "config" else args.deskew == "on"),
        odometry_burst_policy=(
            None if args.odometry_burst_policy == "config" else args.odometry_burst_policy
        ),
        odometry_burst_min_interval_s=args.odometry_burst_min_interval_s,
    )
    payload = artifact.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not args.output:
        print(f"trajectory window drift: {artifact.grade} ({artifact.interpretation})")
    return 0


_ESTIMATE_SHARED_DESTS = frozenset(
    {
        "bag",
        "vehicle_frame",
        "frame_map",
        "topic_kind",
        "max_duration_s",
        "gnss_max_duration_s",
        "camera",
        "no_imu_lidar_translation",
        "imu_lidar_deskew",
        "lidar_lidar_deskew",
        "gnss_lidar_deskew",
        "camera_lidar_motion",
        "camera_lidar_start_scan_min_control_t",
        "acceleration_unit",
        "cache_dir",
        "no_cache",
        "scan_memory_mb",
    }
)


def _cmd_estimate(args: argparse.Namespace) -> int:
    from calibrex.check.cache import default_cache_dir
    from calibrex.check.estimate import (
        ARTIFACT_FILENAME,
        ESTIMATE_PAIRS,
        build_bag_estimate,
        format_estimate_text,
    )
    from calibrex.check.roles import parse_topic_kinds
    from calibrex.check.runner import CheckRunOptions, parse_frame_map
    from calibrex.core.io import write_mapping

    pairs = None
    if args.pairs is not None:
        pairs = tuple(item.strip() for item in args.pairs.split(",") if item.strip())
        unknown = sorted(set(pairs) - ESTIMATE_PAIRS)
        if unknown or not pairs:
            raise CalibrexError(
                f"--pairs: cannot estimate {', '.join(unknown) or '(none given)'}; "
                f"choose from {', '.join(sorted(ESTIMATE_PAIRS))}"
            )
    output_dir: Path = args.output
    run_options = CheckRunOptions(
        pairs=pairs,
        max_duration_s=args.max_duration_s,
        gnss_max_duration_s=args.gnss_max_duration_s,
        camera=args.camera,
        imu_lidar_translation=not args.no_imu_lidar_translation,
        acceleration_unit=args.acceleration_unit,
        imu_lidar_deskew=args.imu_lidar_deskew,
        lidar_lidar_deskew=args.lidar_lidar_deskew,
        gnss_lidar_deskew=args.gnss_lidar_deskew,
        camera_lidar_motion=args.camera_lidar_motion,
        camera_lidar_start_scan_min_control_t=args.camera_lidar_start_scan_min_control_t,
        evidence_dir=output_dir / "evidence",
        base_dir=output_dir,
        cache_dir=None
        if args.no_cache
        else (args.cache_dir if args.cache_dir is not None else default_cache_dir()),
        scan_memory_mb=max(args.scan_memory_mb, 0),
    )

    from calibrex.check.progress import make_progress

    progress = make_progress(sys.stderr, quiet=args.quiet, plain=args.json)
    try:
        artifact = build_bag_estimate(
            args.bag,
            output_dir=output_dir,
            run=run_options,
            tf_files=args.tf,
            vehicle_frame=args.vehicle_frame,
            frame_overrides=parse_frame_map(args.frame_map),
            topic_kinds=parse_topic_kinds(args.topic_kind),
            command=["calibrex", *args.invoked_argv],
            progress=progress,
        )
    finally:
        progress.run_finished()
    payload = artifact.model_dump(mode="json", exclude_none=True)
    write_mapping(output_dir / ARTIFACT_FILENAME, payload)
    if args.html:
        from calibrex.visualization.estimate_report import write_estimate_html

        write_estimate_html(artifact, args.html, artifact_dir=output_dir)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        print(format_estimate_text(artifact, output_dir))
        print(f"artifact: {output_dir / ARTIFACT_FILENAME}")
        if args.html:
            print(f"html report: {args.html}")
    return 0


def _cmd_drift(args: argparse.Namespace) -> int:
    from calibrex.check.cache import default_cache_dir
    from calibrex.check.drift import (
        ARTIFACT_NAME,
        DEFAULT_TIME_OFFSET_FLOORS_S,
        DRIFT_VERDICT_ORDER,
        DriftOptions,
        build_calibration_drift,
        format_drift_text,
    )
    from calibrex.check.estimate import ESTIMATE_PAIRS
    from calibrex.check.progress import make_progress
    from calibrex.check.roles import parse_topic_kinds
    from calibrex.check.runner import CheckRunOptions, parse_frame_map
    from calibrex.core.io import write_mapping

    if len(args.bags) < 2:
        raise CalibrexError("calibrex drift needs at least two bags of the same rig")
    pairs = None
    if args.pairs is not None:
        pairs = tuple(item.strip() for item in args.pairs.split(",") if item.strip())
        unknown = sorted(set(pairs) - ESTIMATE_PAIRS)
        if unknown or not pairs:
            raise CalibrexError(
                f"--pairs: cannot compare {', '.join(unknown) or '(none given)'}; "
                f"choose from {', '.join(sorted(ESTIMATE_PAIRS))}"
            )
    output_dir: Path = args.output
    run_options = CheckRunOptions(
        pairs=pairs,
        max_duration_s=args.max_duration_s,
        gnss_max_duration_s=args.gnss_max_duration_s,
        camera=args.camera,
        imu_lidar_translation=not args.no_imu_lidar_translation,
        acceleration_unit=args.acceleration_unit,
        imu_lidar_deskew=args.imu_lidar_deskew,
        lidar_lidar_deskew=args.lidar_lidar_deskew,
        gnss_lidar_deskew=args.gnss_lidar_deskew,
        camera_lidar_motion=args.camera_lidar_motion,
        camera_lidar_start_scan_min_control_t=args.camera_lidar_start_scan_min_control_t,
        cache_dir=None
        if args.no_cache
        else (args.cache_dir if args.cache_dir is not None else default_cache_dir()),
        scan_memory_mb=max(args.scan_memory_mb, 0),
    )
    try:
        options = DriftOptions(
            sigma_k=args.sigma_k,
            rotation_floor_deg=args.rotation_floor_deg,
            rigid_scan_rotation_floor_deg=args.rigid_scan_rotation_floor_deg,
            translation_floor_m=args.translation_floor_m,
            chi2_alpha=args.chi2_alpha,
            time_offset_floors_s=(
                {"default": args.time_offset_floor_ms * 1e-3}
                if args.time_offset_floor_ms is not None
                else dict(DEFAULT_TIME_OFFSET_FLOORS_S)
            ),
        )
    except ValueError as exc:
        raise CalibrexError(str(exc)) from exc
    progress = make_progress(sys.stderr, quiet=args.quiet, plain=args.json)
    try:
        artifact = build_calibration_drift(
            args.bags,
            output_dir=output_dir,
            run=run_options,
            options=options,
            tf_files=args.tf,
            vehicle_frame=args.vehicle_frame,
            frame_overrides=parse_frame_map(args.frame_map),
            topic_kinds=parse_topic_kinds(args.topic_kind),
            command=["calibrex", *args.invoked_argv],
            progress=progress,
        )
    finally:
        progress.run_finished()
    payload = artifact.model_dump(mode="json", exclude_none=True)
    write_mapping(output_dir / ARTIFACT_NAME, payload)
    if args.html:
        from calibrex.visualization.drift_report import write_drift_html

        write_drift_html(artifact, args.html)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        print(format_drift_text(artifact, output_dir))
        print(f"artifact: {output_dir / ARTIFACT_NAME}")
        if args.html:
            print(f"html report: {args.html}")
    if args.fail_on != "never" and DRIFT_VERDICT_ORDER.index(
        artifact.overall_verdict
    ) >= DRIFT_VERDICT_ORDER.index(args.fail_on):
        return 1
    return 0


def _cmd_check(args: argparse.Namespace) -> int:
    from calibrex.check import build_calibration_check, format_check_table
    from calibrex.check.cache import default_cache_dir
    from calibrex.check.progress import make_progress, use_color
    from calibrex.check.roles import parse_topic_kinds
    from calibrex.check.runner import CheckRunOptions, parse_frame_map
    from calibrex.check.verdict import (
        RIGID_SCAN_ROTATION_FLOOR_DEG,
        VERDICT_ORDER,
        VerdictOptions,
    )
    from calibrex.core.calibration_check import CHECK_PAIR_NAMES
    from calibrex.core.io import write_mapping

    run_options = None
    if not args.plan:
        pairs = None
        if args.pairs is not None:
            pairs = tuple(item.strip() for item in args.pairs.split(",") if item.strip())
            unknown = sorted(set(pairs) - set(CHECK_PAIR_NAMES))
            if unknown or not pairs:
                raise CalibrexError(
                    f"--pairs: unknown pair(s) {', '.join(unknown) or '(none given)'}; "
                    f"choose from {', '.join(CHECK_PAIR_NAMES)}"
                )
        base_dir = args.output.parent if args.output else Path.cwd()
        evidence_dir = args.evidence_dir
        if evidence_dir is None:
            evidence_dir = (
                args.output.with_name(args.output.stem + "_evidence")
                if args.output
                else Path.cwd() / "calibrex_check_evidence"
            )
        run_options = CheckRunOptions(
            verdict=VerdictOptions(
                sigma_k=args.sigma_k,
                rotation_floor_deg=args.rotation_floor_deg,
                translation_floor_m=args.translation_floor_m,
                detection_probe_deg=args.detection_probe_deg,
                focal_scale_floor=args.focal_scale_floor,
            ),
            pairs=pairs,
            max_duration_s=args.max_duration_s,
            gnss_max_duration_s=args.gnss_max_duration_s,
            camera=args.camera,
            imu_lidar_translation=not args.no_imu_lidar_translation,
            acceleration_unit=args.acceleration_unit,
            imu_lidar_deskew=args.imu_lidar_deskew,
            lidar_lidar_deskew=args.lidar_lidar_deskew,
            gnss_lidar_deskew=args.gnss_lidar_deskew,
            camera_lidar_motion=args.camera_lidar_motion,
            camera_lidar_start_scan_min_control_t=args.camera_lidar_start_scan_min_control_t,
            rigid_scan_rotation_floor_deg=(
                args.rigid_scan_rotation_floor_deg
                if args.rigid_scan_rotation_floor_deg is not None
                else RIGID_SCAN_ROTATION_FLOOR_DEG
            ),
            evidence_dir=evidence_dir,
            base_dir=base_dir,
            cache_dir=None
            if args.no_cache
            else (args.cache_dir if args.cache_dir is not None else default_cache_dir()),
            scan_memory_mb=max(args.scan_memory_mb, 0),
        )

    # Progress goes to stderr only: an updating line on a terminal, one line per event
    # when stderr is redirected or --json is given, nothing with --quiet.
    progress = make_progress(sys.stderr, quiet=args.quiet, plain=args.json)

    if args.write_frames_template:
        from calibrex.check.hints import write_frames_template

        # Plan first (seconds) so the template exists before any estimator runs.
        plan = build_calibration_check(
            args.bag,
            tf_files=args.tf,
            vehicle_frame=args.vehicle_frame,
            frame_overrides=parse_frame_map(args.frame_map),
            topic_kinds=parse_topic_kinds(args.topic_kind),
        )
        write_frames_template(args.write_frames_template, plan.topics)
        print(f"frames template: {args.write_frames_template}", file=sys.stderr, flush=True)

    try:
        artifact = build_calibration_check(
            args.bag,
            tf_files=args.tf,
            vehicle_frame=args.vehicle_frame,
            frame_overrides=parse_frame_map(args.frame_map),
            topic_kinds=parse_topic_kinds(args.topic_kind),
            command=["calibrex", *args.invoked_argv],
            run=run_options,
            progress=progress,
        )
    finally:
        progress.run_finished()
    payload = artifact.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.html:
        from calibrex.visualization.check_report import write_check_html

        write_check_html(
            artifact, args.html, artifact_dir=args.output.parent if args.output else Path.cwd()
        )
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        print(format_check_table(artifact, color=use_color(sys.stdout)))
        if args.output:
            print(f"artifact: {args.output}")
        if args.html:
            print(f"html report: {args.html}")
    if (
        artifact.overall_verdict is not None
        and args.fail_on != "never"
        and VERDICT_ORDER.index(artifact.overall_verdict) >= VERDICT_ORDER.index(args.fail_on)
    ):
        return 1
    return 0


def _cmd_capture_readiness(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.pipelines.online import evaluate_rosbag2_capture_readiness

    artifact = evaluate_rosbag2_capture_readiness(args.config)
    payload = artifact.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        print(
            f"calibration readiness: {artifact.grade.upper()} "
            f"({artifact.decision}); {artifact.summary}"
        )
        for recommendation in artifact.recommendations:
            print(f"  next: {recommendation.message}")
        if args.output:
            print(f"  artifact: {args.output}")
    return 1 if args.enforce and artifact.grade != "pass" else 0


def _cmd_continuous_time_lidar_pair(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.pipelines.online import evaluate_continuous_time_lidar_pair

    artifact = evaluate_continuous_time_lidar_pair(args.config)
    payload = artifact.model_dump(mode="json", exclude_none=True)
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        print(
            f"continuous-time LiDAR pair: {artifact.status} "
            f"offset={artifact.estimated_time_offset_sec:.6f}s "
            f"train_rmse={artifact.final_train_rmse_m}"
        )
        print(
            f"  holdout_rmse={artifact.final_holdout_rmse_m} "
            f"rank={artifact.observability.rank} "
            f"condition={artifact.observability.condition_number}"
        )
        print(
            f"  correspondences=train:{artifact.train_correspondence_count} "
            f"holdout:{artifact.holdout_correspondence_count}; "
            f"outliers_rejected={artifact.outlier_rejected_count}"
        )
        print(
            f"  method=voxel:{artifact.options.voxel_strategy} "
            f"outliers:{artifact.options.outlier_policy}"
        )
        print(f"  reason: {artifact.reason}")
        if args.output:
            print(f"  artifact: {args.output}")
    enforce_ok = (
        artifact.status == "converged"
        and artifact.observability.rank is not None
        and artifact.observability.rank >= 6
        and artifact.final_holdout_rmse_m is not None
        and artifact.holdout_correspondence_count >= artifact.options.min_correspondences
    )
    return 1 if args.enforce and not enforce_ok else 0


def _parse_labeled_results(entries: list[str]) -> list[tuple[str, Path]]:
    labeled: list[tuple[str, Path]] = []
    for entry in entries:
        label, separator, path = entry.partition("=")
        if not separator or not label or not path:
            _die(f"report-compare entries must use LABEL=RESULT syntax, got: {entry}")
        labeled.append((label, Path(path)))
    if len(labeled) < 2:
        _die("report-compare requires at least two LABEL=RESULT entries")
    labels = [label for label, _ in labeled]
    duplicates = sorted({label for label in labels if labels.count(label) > 1})
    if duplicates:
        _die(f"duplicate report-compare labels: {', '.join(duplicates)}")
    return labeled


def _cmd_metrics(args: argparse.Namespace) -> int:
    from calibrex.evaluation.registry import list_metric_definitions

    definitions = [
        {
            "name": definition.name,
            "description": definition.description,
            "unit": definition.unit,
            "family": definition.family,
        }
        for definition in list_metric_definitions()
    ]
    if args.json:
        print(json.dumps({"metrics": definitions}, indent=2, sort_keys=True))
    else:
        for definition in definitions:
            unit = f" [{definition['unit']}]" if definition["unit"] else ""
            print(f"{definition['name']}{unit}: {definition['description']}")
    return 0


def _cmd_public_datasets_list(args: argparse.Namespace) -> int:
    from calibrex.data.public_datasets import load_public_dataset_catalog

    catalog = load_public_dataset_catalog()
    payload = {
        "datasets": [
            {
                "id": dataset_id,
                "name": entry.name,
                "family": entry.family,
                "domain": entry.domain,
                "recommended_pipeline": entry.recommended_pipeline,
                "slac_config": entry.slac_config,
            }
            for dataset_id, entry in sorted(catalog.datasets.items())
        ]
    }
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        for entry in payload["datasets"]:
            print(
                f"{entry['id']}: {entry['name']} "
                f"({entry['domain']}, {entry['recommended_pipeline']})"
            )
    return 0


def _cmd_public_datasets_show(args: argparse.Namespace) -> int:
    from calibrex.data.public_datasets import load_public_dataset_catalog

    catalog = load_public_dataset_catalog()
    try:
        entry = catalog.datasets[args.dataset]
    except KeyError as exc:
        _die(f"unknown public dataset: {args.dataset}")
        raise AssertionError from exc
    payload = entry.model_dump(mode="json")
    payload["id"] = args.dataset
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        for key, value in payload.items():
            print(f"{key}: {value}")
    return 0


def _cmd_demo_livox_evidence(args: argparse.Namespace) -> int:
    from calibrex.core.assessment import AssessmentArtifact
    from calibrex.core.evidence_bundle import (
        verify_evidence_bundle,
        write_evidence_bundle_verification,
    )
    from calibrex.core.io import read_mapping
    from calibrex.data.downloads import (
        download_livox_horizon_horizon_pcd_sample,
        livox_horizon_horizon_pcd_sample_path,
    )
    from calibrex.pipelines.calibrate import CalibrationRunOptions, run_calibration

    dataset_path = livox_horizon_horizon_pcd_sample_path(args.data_dir)
    if args.no_download:
        _require_livox_demo_files(dataset_path)
        downloaded = False
    else:
        downloaded_result = download_livox_horizon_horizon_pcd_sample(args.data_dir)
        dataset_path = downloaded_result.path
        downloaded = downloaded_result.downloaded

    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)
    demo_config = output_dir / "demo_config.yaml"
    _write_demo_config(args.config, demo_config, dataset_path, output_dir)

    result = run_calibration(
        demo_config,
        CalibrationRunOptions(output_dir=output_dir, seed=args.seed),
    )
    if result is None:
        _die("Livox evidence demo did not produce a result")

    evidence_path = output_dir / "evidence.json"
    assessment_path = output_dir / "assessment.json"
    bundle_path = output_dir / "bundle.json"
    assessment = AssessmentArtifact.model_validate(read_mapping(assessment_path))
    verification = verify_evidence_bundle(bundle_path, require_raw_recomputed=True)
    verification_path = output_dir / "verification.json"
    verification = write_evidence_bundle_verification(
        verification_path,
        verification,
        source_bundle_path=bundle_path,
    )
    payload = {
        "status": "ok" if verification.valid else "invalid_bundle",
        "dataset": str(dataset_path),
        "downloaded": downloaded,
        "config": str(demo_config),
        "result": str(output_dir / "result.yaml"),
        "evidence": str(evidence_path),
        "assessment": str(assessment_path),
        "assessment_status": assessment.status,
        "assessment_reason": assessment.reason,
        "bundle": str(bundle_path),
        "verification": str(verification_path),
        "bundle_valid": verification.valid,
        "bundle_issues": verification.issues,
        "raw_recomputed_required": verification.raw_recomputed_required,
        "html_report": str(output_dir / "report.html"),
    }
    _emit(payload, args.json)
    if not verification.valid:
        return 1
    if args.strict_assessment and assessment.status != "pass":
        return 1
    return 0


def _require_livox_demo_files(dataset_path: Path) -> None:
    from calibrex.data.downloads import LIVOX_BASE_PCD_NAME, LIVOX_TARGET_PCD_NAME

    missing = [
        name
        for name in (LIVOX_BASE_PCD_NAME, LIVOX_TARGET_PCD_NAME)
        if not (dataset_path / name).exists()
    ]
    if missing:
        _die(
            "Livox demo data is missing: "
            f"{', '.join(missing)} under {dataset_path}. "
            "Run without --no-download or use tools/download_public_dataset.py."
        )


def _write_demo_config(
    source_config: Path,
    output_config: Path,
    dataset_path: Path,
    output_dir: Path,
) -> None:
    from calibrex.core.io import read_mapping, write_mapping

    config_payload = read_mapping(source_config)
    dataset = config_payload.get("dataset")
    if not isinstance(dataset, dict):
        _die(f"{source_config} does not contain a dataset mapping")
    dataset["path"] = str(dataset_path)
    project = config_payload.get("project")
    if isinstance(project, dict):
        project["output_dir"] = str(output_dir)
    write_mapping(output_config, config_payload)


def _cmd_demo_kitti_lidar_camera_evidence(args: argparse.Namespace) -> int:
    from calibrex.core.assessment import AssessmentArtifact
    from calibrex.core.evidence_bundle import (
        verify_evidence_bundle,
        write_evidence_bundle_verification,
    )
    from calibrex.core.io import read_mapping
    from calibrex.pipelines.calibrate import CalibrationRunOptions, run_calibration

    config_payload = read_mapping(args.config)
    dataset_section = config_payload.get("dataset")
    if not isinstance(dataset_section, dict) or "path" not in dataset_section:
        _die(f"{args.config} does not contain a dataset mapping")
    if args.dataset_path is not None:
        dataset_path = Path(args.dataset_path)
    else:
        configured_dataset_path = Path(str(dataset_section["path"]))
        config_relative_path = args.config.parent / configured_dataset_path
        dataset_path = (
            configured_dataset_path
            if configured_dataset_path.is_absolute() or configured_dataset_path.exists()
            else config_relative_path
        )
    _require_kitti_lidar_camera_demo_files(dataset_path)

    output_dir = Path(args.output_dir)
    output_dir.mkdir(parents=True, exist_ok=True)
    demo_config = output_dir / "demo_config.yaml"
    _write_demo_config(args.config, demo_config, dataset_path, output_dir)

    result = run_calibration(
        demo_config,
        CalibrationRunOptions(output_dir=output_dir, seed=args.seed),
    )
    if result is None:
        _die("KITTI camera-LiDAR evidence demo did not produce a result")

    evidence_path = output_dir / "evidence.json"
    assessment_path = output_dir / "assessment.json"
    bundle_path = output_dir / "bundle.json"
    assessment = AssessmentArtifact.model_validate(read_mapping(assessment_path))
    verification = verify_evidence_bundle(bundle_path, require_raw_recomputed=True)
    verification_path = output_dir / "verification.json"
    verification = write_evidence_bundle_verification(
        verification_path,
        verification,
        source_bundle_path=bundle_path,
    )
    payload = {
        "status": "ok" if verification.valid else "invalid_bundle",
        "dataset": str(dataset_path),
        "config": str(demo_config),
        "result": str(output_dir / "result.yaml"),
        "evidence": str(evidence_path),
        "assessment": str(assessment_path),
        "assessment_status": assessment.status,
        "assessment_reason": assessment.reason,
        "bundle": str(bundle_path),
        "verification": str(verification_path),
        "bundle_valid": verification.valid,
        "bundle_issues": verification.issues,
        "raw_recomputed_required": verification.raw_recomputed_required,
        "html_report": str(output_dir / "report.html"),
        "note": (
            "camera-LiDAR metrics are diagnostic overlay evidence on the LiDAR "
            "candidate extrinsic, scored against the calib_velo_to_cam.txt "
            "dataset reference; this is not a standalone camera calibration. "
            "Selected camera, Velodyne, and calibration inputs are SHA-256 "
            "bound and raw-recomputation verification is enforced."
        ),
    }
    _emit(payload, args.json)
    if not verification.valid:
        return 1
    if args.strict_assessment and assessment.status != "pass":
        return 1
    return 0


def _require_kitti_lidar_camera_demo_files(dataset_path: Path) -> None:
    required_paths = {
        "calib_velo_to_cam.txt": dataset_path.parent / "calib_velo_to_cam.txt",
        "calib_cam_to_cam.txt": dataset_path.parent / "calib_cam_to_cam.txt",
        "image_02/data": dataset_path / "image_02" / "data",
        "velodyne_points/data": dataset_path / "velodyne_points" / "data",
    }
    missing = [name for name, path in required_paths.items() if not path.exists()]
    if missing:
        _die(
            "KITTI camera-LiDAR demo data is missing: "
            f"{', '.join(missing)} under {dataset_path} (and its parent). "
            "Point --dataset-path at a local KITTI raw sequence obtained through "
            "the official KITTI raw download flow, or use the small synthetic "
            "fixture bundled with the example config."
        )


def _cmd_convert_kitti_raw(args: argparse.Namespace) -> int:
    from calibrex.data.kitti_raw_to_rosbag2 import convert_kitti_raw_to_rosbag2

    result = convert_kitti_raw_to_rosbag2(
        args.drives,
        args.output,
        calibration_dir=args.calib_dir,
        command=["calibrex", *args.invoked_argv],
        overwrite=args.overwrite,
        camera=args.camera,
        velodyne_time=args.velodyne_time,
    )
    payload = {
        "bag": str(result.bag),
        "provenance": str(result.provenance_path),
        "message_counts": result.message_counts,
    }
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        counts = ", ".join(f"{topic}: {count}" for topic, count in result.message_counts.items())
        print(f"wrote {result.bag} ({counts})")
        print(f"provenance: {result.provenance_path}")
    return 0


def _cmd_convert_kitti360(args: argparse.Namespace) -> int:
    from calibrex.data.kitti360_to_rosbag2 import convert_kitti360_to_rosbag2

    result = convert_kitti360_to_rosbag2(
        args.dataset_root,
        args.output,
        sequence=args.sequence,
        calibration_dir=args.calib_dir,
        camera=args.camera,
        velodyne_time=args.velodyne_time,
        scan_period_s=args.scan_period,
        start_frame=args.start_frame,
        max_frames=args.max_frames,
        overwrite=args.overwrite,
        command=["calibrex", *args.invoked_argv],
    )
    payload = {
        "bag": str(result.bag),
        "provenance": str(result.provenance_path),
        "message_counts": result.message_counts,
    }
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    else:
        print(f"wrote {result.bag} ({result.message_counts})")
        print(f"provenance: {result.provenance_path}")
    return 0


def _cmd_kitti_import_calib(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.data.kitti import read_kitti_initial_transforms

    transforms = {
        name: {
            "convention": "T_parent_child",
            **transform.as_dict(),
        }
        for name, transform in sorted(read_kitti_initial_transforms(args.path).items())
    }
    payload = {"transforms": transforms}
    if args.output:
        write_mapping(args.output, payload)
    if args.json:
        print(json.dumps(payload, indent=2, sort_keys=True))
    elif not args.output:
        _emit(payload, as_json=False)
    return 0


def _cmd_demo_kitti_falsification_benchmark(args: argparse.Namespace) -> int:
    from calibrex.evaluation.kitti_falsification_benchmark import run_kitti_falsification_benchmark

    try:
        benchmark = run_kitti_falsification_benchmark(
            args.dataset_path,
            config_path=args.config,
            output_dir=args.output_dir,
            max_frames=args.max_frames,
            projection_sample_points=args.projection_sample_points,
            seed=args.seed,
            source_url=args.source_url,
            source_note=args.source_note,
        )
    except (OSError, RuntimeError, ValueError) as exc:
        _die(str(exc))
    payload = {
        "status": benchmark.status,
        "falsification_passed": benchmark.status == "pass",
        "reason": benchmark.reason,
        "benchmark": str(Path(args.output_dir) / "benchmark.json"),
        "dataset": benchmark.dataset_path,
        "selected_frame_count": len(benchmark.selected_frame_ids),
        "trials": {
            trial.candidate_id: {
                "assessment_status": trial.assessment_status,
                "bundle_valid": trial.bundle_valid,
            }
            for trial in benchmark.trials
        },
    }
    _emit(payload, args.json)
    return 1 if args.enforce and benchmark.status != "pass" else 0


def _cmd_external_run_import_sensor_calib_tas(args: argparse.Namespace) -> int:
    from calibrex.core.io import write_mapping
    from calibrex.importers.sensor_calib_tas import sensor_calib_tas_frames

    if args.source.resolve() == args.output.resolve():
        _die("the output must not overwrite the sensor_calib_tas source")
    try:
        frames = sensor_calib_tas_frames(args.source, tool_version=args.tool_version)
    except ValueError as exc:
        _die(str(exc))
    write_mapping(args.output, frames.model_dump(mode="json", exclude_none=True))
    _emit(
        {
            "frames_file": str(args.output),
            "source": str(args.source),
            "source_kind": frames.provenance.source_kind if frames.provenance else None,
            "frames": [f"{entry.parent} -> {entry.name}" for entry in frames.frames],
            "usage": f"calibrex check <driving bag> --tf {args.output}",
        },
        args.json,
    )
    return 0


def _cmd_external_run_import_kalibr(args: argparse.Namespace) -> int:
    from calibrex.importers.kalibr import import_kalibr_camchain

    if args.source.resolve() == args.output.resolve():
        _die("external-run output must not overwrite the Kalibr source artifact")
    license_spdx = (
        None
        if str(args.license_spdx).strip().lower() == "unknown"
        else str(args.license_spdx).strip()
    )
    artifact = import_kalibr_camchain(
        args.source,
        input_artifacts=tuple(args.input_artifact),
        expected_source_sha256=args.expected_source_sha256,
        tool_version=args.tool_version,
        source_commit=args.source_commit,
        license_spdx=license_spdx,
        training_isolation_declared=args.training_isolation_declared,
        training_isolation_evidence=args.training_isolation_evidence,
    )
    artifact.save(args.output)
    _emit(
        {
            "status": artifact.status,
            "external_run": str(args.output),
            "source": str(args.source),
            "source_sha256": artifact.provenance.source_artifact_sha256,
            "transform_count": len(artifact.parsed_outputs.transforms),
            "time_offset_count": len(artifact.parsed_outputs.time_offsets_seconds),
            "camera_count": len(artifact.parsed_outputs.intrinsics),
            "warnings": artifact.warnings,
        },
        args.json,
    )
    return 0 if artifact.status == "success" else 1


def _cmd_external_run_evaluate_camera_imu(args: argparse.Namespace) -> int:
    from calibrex.evaluation.external_camera_imu import evaluate_external_camera_imu

    if args.output.resolve() in {args.external_run.resolve(), args.recording.resolve()}:
        _die("evidence output must not overwrite its inputs")
    command = [
        "calibrex",
        "external-run",
        "evaluate-camera-imu",
        str(args.external_run),
        "--recording",
        str(args.recording),
        "--camera",
        str(args.camera),
        "--output",
        str(args.output),
    ]
    artifact = evaluate_external_camera_imu(
        args.external_run,
        args.recording,
        camera_name=args.camera,
        evaluation_id=args.evaluation_id,
        command=command,
    )
    artifact.save(args.output)
    _emit(
        {
            "status": artifact.status,
            "evidence": str(args.output),
            "holdout_rate_rmse_rad_s": artifact.holdout_rate_rmse_rad_s,
            "control_detection_fraction": artifact.control_detection_fraction,
            "lever_arm_status": (None if artifact.lever_arm is None else artifact.lever_arm.status),
            "holdout_specific_force_rmse_m_s2": (
                None
                if artifact.lever_arm is None
                else artifact.lever_arm.holdout_specific_force_rmse_m_s2
            ),
            "reasons": artifact.reasons,
            "warnings": artifact.warnings,
        },
        args.json,
    )
    return 0 if artifact.status in {"pass", "warn"} else 1


def _cmd_external_run_synthesize_camera_imu_fixture(args: argparse.Namespace) -> int:
    from calibrex.evaluation.external_camera_imu import write_synthetic_camera_imu_fixture

    fixture = write_synthetic_camera_imu_fixture(
        args.output_dir,
        seed=args.seed,
        rotation_error_deg=tuple(args.rotation_error_deg),
        timeshift_error_sec=args.timeshift_error_sec,
        translation_error_m=tuple(args.translation_error_m),
        motion=args.motion,
        accelerometer=not args.no_accelerometer,
    )
    _emit(
        {
            "camchain": str(fixture.camchain_path),
            "fitting_recording": str(fixture.fitting_recording_path),
            "evaluation_recording": str(fixture.evaluation_recording_path),
            "synthetic": True,
        },
        args.json,
    )
    return 0


def _cmd_external_run_import_koide(args: argparse.Namespace) -> int:
    """Import one Koide native result through the typed external-run boundary."""
    from calibrex.importers.koide import import_koide_result


    if args.source.resolve() == args.output.resolve():
        _die("external-run output must not overwrite the Koide source artifact")
    license_spdx = (
        None
        if str(args.license_spdx).strip().lower() == "unknown"
        else str(args.license_spdx).strip()
    )
    artifact = import_koide_result(
        args.source,
        lidar_frame=args.lidar_frame,
        camera_frame=args.camera_frame,
        input_artifacts=tuple(args.input_artifact),
        expected_source_sha256=args.expected_source_sha256,
        tool_version=args.tool_version,
        source_commit=args.source_commit,
        license_spdx=license_spdx,
        training_isolation_declared=args.training_isolation_declared,
        training_isolation_evidence=args.training_isolation_evidence,
        training_data_ids_sha256=args.training_data_ids_sha256,
        holdout_data_ids_sha256=args.holdout_data_ids_sha256,
    )
    artifact.save(args.output)
    _emit(
        {
            "status": artifact.status,
            "external_run": str(args.output),
            "source": str(args.source),
            "source_sha256": artifact.provenance.source_artifact_sha256,
            "transform_count": len(artifact.parsed_outputs.transforms),
            "warnings": artifact.warnings,
        },
        args.json,
    )
    return 0 if artifact.status == "success" else 1


def _cmd_external_run_koide(args: argparse.Namespace) -> int:
    """Run the typed Koide workflow declared by a Calibrex config."""
    from calibrex.core.config import load_config
    from calibrex.core.frames import FrameGraph
    from calibrex.data.inspect import inspect_dataset
    from calibrex.solvers.koide_lidar_camera_solver import KoideLidarCameraSolver


    if args.config.resolve() == args.output.resolve():
        _die("Koide external-run output must not overwrite the config")
    config = load_config(args.config)
    # ``--input-artifact`` is a CLI-level provenance input.  Preserve the
    # factor's declared paths and append these explicit files before the
    # solver builds its typed runner config, so they are actually digest-bound
    # in the resulting external-run artifact.
    if args.input_artifact:
        for factor_name in (
            "koide_lidar_camera",
            "direct_visual_lidar_calibration",
            "lidar_camera_targetless_baseline",
        ):
            factor = config.pipeline.factors.get(factor_name)
            if factor is None or not factor.enabled:
                continue
            raw_paths = factor.options.get(
                "input_paths",
                factor.options.get("input_artifacts", []),
            )
            if isinstance(raw_paths, (str, Path)):
                paths = [str(raw_paths)]
            elif isinstance(raw_paths, (list, tuple)):
                paths = [str(path) for path in raw_paths]
            else:
                paths = []
            for path in args.input_artifact:
                text_path = str(path)
                if text_path not in paths:
                    paths.append(text_path)
            factor.options["input_paths"] = paths
            break
    inspection = inspect_dataset(config.dataset)
    result = KoideLidarCameraSolver().solve(
        config,
        FrameGraph.from_config(config),
        inspection,
    )
    if result.external_run is None:
        _die("Koide factor did not produce an external-run artifact")
    result.external_run.save(args.output)
    _emit(
        {
            "status": result.external_run.status,
            "external_run": str(args.output),
            "transform_count": len(result.external_run.parsed_outputs.transforms),
            "stage_count": len(result.external_run.execution.stages),
            "warnings": result.external_run.warnings,
        },
        args.json,
    )
    return 0 if result.external_run.status == "success" else 1


def _cmd_kitti_lock_benchmark_input(args: argparse.Namespace) -> int:
    from calibrex.data.kitti_benchmark import build_kitti_raw_0005_benchmark_input

    command = f"calibrex kitti lock-benchmark-input {args.path} --output {args.output}"
    manifest = build_kitti_raw_0005_benchmark_input(args.path, command=command)
    manifest.save(args.output)
    payload = {
        "status": "ok",
        "dataset_id": manifest.dataset_id,
        "sequence_id": manifest.sequence_id,
        "frame_count": len(manifest.frame_ids),
        "file_count": len(manifest.files),
        "input_sha256": manifest.input_sha256,
        "output": str(args.output),
    }
    _emit(payload, args.json)
    return 0


def _cmd_kitti_benchmark_i2i(args: argparse.Namespace) -> int:
    from calibrex.evaluation.pandey_recovery_benchmark import (
        load_kitti_i2i_benchmark_data,
        run_kitti_i2i_recovery_benchmark,
    )

    if args.max_iterations < 0:
        _die("--max-iterations must be non-negative")
    command = (
        f"calibrex kitti benchmark-i2i {args.input_manifest} "
        f"--definition-output {args.definition_output} --output {args.output}"
    )
    data = load_kitti_i2i_benchmark_data(
        args.input_manifest,
        sequence_path=args.sequence_path,
        max_points_per_frame=args.max_points_per_frame,
    )
    definition, benchmark = run_kitti_i2i_recovery_benchmark(
        data,
        command=command,
        max_iterations=args.max_iterations,
    )
    definition.save(args.definition_output)
    benchmark.save(args.output)
    coarse = benchmark.method_summaries["pandey_i2i_vectorized_safe_coarse_bb_v03"]
    baseline = benchmark.method_summaries["pandey_i2i_scalar_bb_v01"]
    baseline_runtime = baseline.runtime_seconds.mean
    coarse_runtime = coarse.runtime_seconds.mean
    runtime_speedup = (
        baseline_runtime / coarse_runtime
        if baseline_runtime is not None and coarse_runtime is not None and coarse_runtime > 0.0
        else None
    )
    baseline_trials = {
        trial.split_id: trial
        for trial in benchmark.trials
        if trial.method_id == "pandey_i2i_scalar_bb_v01"
    }
    coarse_trials = {
        trial.split_id: trial
        for trial in benchmark.trials
        if trial.method_id == "pandey_i2i_vectorized_safe_coarse_bb_v03"
    }
    accuracy_non_degraded = all(
        split_id in coarse_trials
        and baseline_trial.status == coarse_trials[split_id].status == "success"
        and coarse_trials[split_id].metrics["translation_error_m"]
        <= baseline_trial.metrics["translation_error_m"] + 1.0e-12
        and coarse_trials[split_id].metrics["rotation_error_deg"]
        <= baseline_trial.metrics["rotation_error_deg"] + 1.0e-12
        and coarse_trials[split_id].metrics["holdout_normalized_mutual_information"] + 1.0e-12
        >= baseline_trial.metrics["holdout_normalized_mutual_information"]
        and coarse_trials[split_id].metrics["recovered"] + 1.0e-12
        >= baseline_trial.metrics["recovered"]
        for split_id, baseline_trial in baseline_trials.items()
    )
    runtime_improved = runtime_speedup is not None and runtime_speedup > 1.0
    payload = {
        "status": "ok",
        "definition": str(args.definition_output),
        "benchmark": str(args.output),
        "input_sha256": data.manifest.input_sha256,
        "trial_count": len(benchmark.trials),
        "baseline_failure_rate": baseline.failure_rate,
        "coarse_failure_rate": coarse.failure_rate,
        "baseline_runtime_mean_s": baseline_runtime,
        "coarse_runtime_mean_s": coarse_runtime,
        "runtime_speedup": runtime_speedup,
        "accuracy_non_degraded": accuracy_non_degraded,
        "runtime_improved": runtime_improved,
        "performance_gate_passed": accuracy_non_degraded and runtime_improved,
    }
    _emit(payload, args.json)
    return 0


def _cmd_camera_lidar_freeze_rotation_protocol(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_rotation_benchmark import build_borer_rotation_protocol

    command = [
        "calibrex",
        "camera-lidar",
        "freeze-rotation-protocol",
        str(args.problem),
        "--output",
        str(args.output),
        "--perturbation-count",
        str(args.perturbation_count),
        "--rotation-deg",
        str(args.rotation_deg),
        "--histogram-bins",
        str(args.histogram_bins),
        "--min-visible-points",
        str(args.min_visible_points),
        "--bound-deg",
        str(args.bound_deg),
        "--initial-step-deg",
        str(args.initial_step_deg),
        "--minimum-step-deg",
        str(args.minimum_step_deg),
        "--max-evaluations",
        str(args.max_evaluations),
    ]
    try:
        protocol = build_borer_rotation_protocol(
            args.problem,
            perturbation_count=args.perturbation_count,
            rotation_magnitude_deg=args.rotation_deg,
            histogram_bins=args.histogram_bins,
            min_visible_points=args.min_visible_points,
            bound_deg=args.bound_deg,
            initial_step_deg=args.initial_step_deg,
            minimum_step_deg=args.minimum_step_deg,
            max_evaluations=args.max_evaluations,
            command=tuple(command),
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    protocol.save(args.output)
    _emit(
        {
            "status": "ok",
            "protocol_id": protocol.protocol_id,
            "problem_sha256": protocol.problem_sha256,
            "frame_count": len(protocol.frame_ids),
            "perturbation_count": protocol.perturbation_count,
            "rotation_magnitude_deg": protocol.rotation_magnitude_deg,
            "output": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_freeze_six_dof_protocol(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_rotation_benchmark import build_borer_six_dof_protocol

    command = [
        "calibrex",
        "camera-lidar",
        "freeze-six-dof-protocol",
        str(args.problem),
        "--output",
        str(args.output),
        "--perturbation-count",
        str(args.perturbation_count),
        "--rotation-deg",
        str(args.rotation_deg),
        "--translation-m",
        str(args.translation_m),
        "--histogram-bins",
        str(args.histogram_bins),
        "--min-visible-points",
        str(args.min_visible_points),
        "--rotation-bound-deg",
        str(args.rotation_bound_deg),
        "--translation-bound-m",
        str(args.translation_bound_m),
        "--initial-rotation-step-deg",
        str(args.initial_rotation_step_deg),
        "--initial-translation-step-m",
        str(args.initial_translation_step_m),
        "--minimum-rotation-step-deg",
        str(args.minimum_rotation_step_deg),
        "--minimum-translation-step-m",
        str(args.minimum_translation_step_m),
        "--max-evaluations",
        str(args.max_evaluations),
    ]
    try:
        protocol = build_borer_six_dof_protocol(
            args.problem,
            perturbation_count=args.perturbation_count,
            rotation_magnitude_deg=args.rotation_deg,
            translation_magnitude_m=args.translation_m,
            histogram_bins=args.histogram_bins,
            min_visible_points=args.min_visible_points,
            rotation_bound_deg=args.rotation_bound_deg,
            translation_bound_m=args.translation_bound_m,
            initial_rotation_step_deg=args.initial_rotation_step_deg,
            initial_translation_step_m=args.initial_translation_step_m,
            minimum_rotation_step_deg=args.minimum_rotation_step_deg,
            minimum_translation_step_m=args.minimum_translation_step_m,
            max_evaluations=args.max_evaluations,
            command=tuple(command),
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    protocol.save(args.output)
    _emit(
        {
            "status": "ok",
            "protocol_id": protocol.protocol_id,
            "problem_sha256": protocol.problem_sha256,
            "frame_count": len(protocol.frame_ids),
            "perturbation_count": protocol.perturbation_count,
            "rotation_magnitude_deg": protocol.rotation_magnitude_deg,
            "translation_magnitude_m": protocol.translation_magnitude_m,
            "output": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_benchmark_koide_pilot(args: argparse.Namespace) -> int:
    from calibrex.evaluation.koide_pilot import KoidePilotThresholds, run_koide_pilot

    try:
        thresholds = KoidePilotThresholds(
            max_frames=args.max_frames,
            max_points=args.max_points,
            holdout_ratio=args.holdout_ratio,
            split_seed=args.split_seed,
            min_holdout_projection_ratio=args.min_holdout_projection_ratio,
            min_holdout_edge_alignment=args.min_holdout_edge_alignment,
            min_holdout_depth_edge_alignment=args.min_holdout_depth_edge_alignment,
            known_bad_min_metric_delta=args.known_bad_min_metric_delta,
        )
        artifact = run_koide_pilot(
            args.dataset_path,
            args.candidate,
            output_directory=args.output_dir,
            config_path=args.config,
            readiness_path=args.readiness,
            input_manifest_path=args.input_manifest,
            camera_frame=args.camera_frame,
            lidar_frame=args.lidar_frame,
            camera_stream=args.camera_stream,
            lidar_stream=args.lidar_stream,
            thresholds=thresholds,
            command=[
                "calibrex",
                "camera-lidar",
                "benchmark-koide-pilot",
                str(args.dataset_path),
            ],
            official_command=(shlex.split(args.official_command) if args.official_command else ()),
            tool_source_commit=args.tool_source_commit,
            container_digest=args.container_digest,
        )
    except (OSError, ValueError, RuntimeError) as exc:
        _die(str(exc))
    payload = {
        "status": artifact.status,
        "adoption_decision": artifact.adoption_decision,
        "admissible": artifact.admissible,
        "reason": artifact.reason,
        "pilot": str(args.output_dir / "pilot.json"),
        "execution_manifest": str(args.output_dir / "execution-manifest.yaml"),
        "known_bad_detected_count": artifact.known_bad_detected_count,
        "known_bad_required_count": artifact.known_bad_required_count,
    }
    _emit(payload, as_json=args.json)
    return 0 if artifact.status in {"PASS", "WARN", "INCONCLUSIVE"} else 1


def _cmd_camera_lidar_koide_handoff(args: argparse.Namespace) -> int:
    """Validate the immutable Koide lock and print operator next actions."""
    from calibrex.core.koide_handoff import load_koide_execution_lock


    try:
        lock = load_koide_execution_lock(args.lock)
    except (OSError, ValueError) as exc:
        _die(str(exc))
    payload = {
        "status": "handoff_only",
        "executes_external_process": False,
        "lock": str(args.lock),
        "lock_id": lock.lock_id,
        "lock_sha256": lock.lock_sha256,
        "profile": lock.profile,
        "initial_guess_mode": lock.initial_guess_mode,
        "superglue_policy": lock.superglue_policy,
        "source_repository": lock.source.repository,
        "source_commit": lock.source.commit,
        "license_spdx": lock.source.license_spdx,
        "image_digest": lock.image.digest,
        "base_image": lock.image.base_image,
        "base_image_digest": lock.image.base_image_digest,
        "base_image_digest_required_for_rebuild": (
            lock.image.base_image_digest_required_for_rebuild
        ),
        "runtime": {
            "docker_available": shutil.which("docker") is not None,
            "podman_available": shutil.which("podman") is not None,
            "ros2_available": shutil.which("ros2") is not None,
            "colcon_available": shutil.which("colcon") is not None,
        },
        "next_actions": lock.operator_steps,
        "stages": [stage.model_dump(mode="json") for stage in lock.stages],
    }
    _emit(payload, args.json)
    return 0


def _cmd_camera_lidar_koide_real_plan(args: argparse.Namespace) -> int:
    """Materialize the non-executing real Koide plan."""
    from calibrex.core.koide_real_pilot import build_koide_real_pilot_request


    try:
        request = build_koide_real_pilot_request(
            camera_frame=args.camera_frame,
            lidar_frame=args.lidar_frame,
            command=["calibrex", "camera-lidar", "koide-real-plan"],
        )
        request.save(args.output)
    except (OSError, ValueError) as exc:
        _die(str(exc))
    _emit(
        {
            "status": request.status,
            "executes_external_process": False,
            "request": str(args.output),
            "request_id": request.request_id,
            "request_sha256": request.request_sha256,
            "source_commit": request.execution.source_commit,
            "container_digest": request.execution.image_digest,
            "official_result_claim": request.official_result_claim,
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_koide_real_verify(args: argparse.Namespace) -> int:
    """Verify a real Koide handoff's supplied evidence without running Koide."""
    from calibrex.core.koide_real_pilot import verify_koide_real_pilot_request


    try:
        verification = verify_koide_real_pilot_request(
            args.request,
            dataset_path=args.dataset,
            dataset_archive_path=args.archive,
            input_manifest_path=args.input_manifest,
            readiness_path=args.readiness,
            config_path=args.config,
            candidate_path=args.candidate,
            external_run_path=args.external_run,
            execution_log_path=args.execution_log,
            environment_path=args.environment,
            evidence_label=args.evidence_label,
            command=["calibrex", "camera-lidar", "koide-real-verify", str(args.request)],
        )
        verification.save(args.output)
    except (OSError, ValueError) as exc:
        _die(str(exc))
    _emit(
        {
            "status": verification.status,
            "official_evidence": verification.official_evidence,
            "evidence_label": verification.evidence_label,
            "verification": str(args.output),
            "request_id": verification.request_id,
            "reasons": verification.reasons,
        },
        args.json,
    )
    return 0 if verification.status == "READY_FOR_PILOT" else 1


def _cmd_camera_lidar_koide_real_finalize(args: argparse.Namespace) -> int:
    """Finalize a verified Koide pilot; never execute the external provider."""
    from calibrex.core.koide_real_pilot import finalize_koide_real_pilot


    try:
        finalization = finalize_koide_real_pilot(
            args.request,
            args.verification,
            args.pilot,
            output_path=args.output,
            evidence_label=args.evidence_label,
            command=["calibrex", "camera-lidar", "koide-real-finalize", str(args.request)],
        )
    except (OSError, ValueError) as exc:
        _die(str(exc))
    _emit(
        {
            "status": finalization.status,
            "execution_state": finalization.execution_state,
            "official_result_claim": finalization.official_result_claim,
            "finalization": str(args.output),
            "request_id": finalization.request_id,
            "reasons": finalization.reasons,
        },
        args.json,
    )
    return 0 if finalization.status in {"PASS", "TEST_ONLY"} else 1


def _cmd_camera_lidar_export_koide_pilot(args: argparse.Namespace) -> int:
    from calibrex.evaluation.koide_pilot import export_koide_pilot_autoware

    try:
        paths = export_koide_pilot_autoware(
            args.pilot,
            args.output,
            base_frame=args.base_frame,
            sensor_frame=args.sensor_frame,
            static_tf_output=args.static_tf_output,
            manifest_output=args.manifest_output,
            overwrite=args.force,
        )
    except (OSError, ValueError, RuntimeError) as exc:
        _die(str(exc))
    payload = {"status": "ok", **{name: str(path) for name, path in paths.items()}}
    _emit(payload, as_json=args.json)
    return 0


def _cmd_camera_lidar_build_kitti_problem(args: argparse.Namespace) -> int:
    from calibrex.data.kitti_camera_lidar_problem import build_kitti_raw_camera_lidar_problem

    command = [
        "calibrex",
        "camera-lidar",
        "build-kitti-problem",
        str(args.sequence_path),
        str(args.depth_provider),
        "--output",
        str(args.output),
        "--camera-stream",
        args.camera_stream,
        "--rotation-bound-deg",
        str(args.rotation_bound_deg),
        "--translation-bound-m",
        str(args.translation_bound_m),
    ]
    if args.lidar_directory is not None:
        command.extend(["--lidar-directory", str(args.lidar_directory)])
    if args.lidar_manifest is not None:
        command.extend(["--lidar-manifest", str(args.lidar_manifest)])
    if args.dataset_id is not None:
        command.extend(["--dataset-id", args.dataset_id])
    if args.problem_id is not None:
        command.extend(["--problem-id", args.problem_id])
    try:
        problem = build_kitti_raw_camera_lidar_problem(
            args.sequence_path,
            args.depth_provider,
            camera_stream=args.camera_stream,
            lidar_directory=args.lidar_directory,
            lidar_manifest_path=args.lidar_manifest,
            dataset_id=args.dataset_id,
            problem_id=args.problem_id,
            rotation_bound_deg=args.rotation_bound_deg,
            translation_bound_m=args.translation_bound_m,
            command=tuple(command),
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    problem.save(args.output)
    _emit(
        {
            "status": "ok",
            "problem_id": problem.problem_id,
            "dataset_id": problem.dataset_id,
            "sequence_id": problem.sequence_id,
            "frame_count": len(problem.observations),
            "depth_provider_sha256": problem.depth_provider_sha256,
            "output": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_build_kitti360_problem(args: argparse.Namespace) -> int:
    from calibrex.data.kitti360_camera_lidar_problem import build_kitti360_camera_lidar_problem

    command = [
        "calibrex",
        "camera-lidar",
        "build-kitti360-problem",
        str(args.sequence_path),
        str(args.depth_provider),
        "--output",
        str(args.output),
        "--camera-stream",
        args.camera_stream,
        "--split-id",
        args.split_id,
        "--rotation-bound-deg",
        str(args.rotation_bound_deg),
        "--translation-bound-m",
        str(args.translation_bound_m),
    ]
    if args.calibration_root is not None:
        command.extend(["--calibration-root", str(args.calibration_root)])
    if args.lidar_directory is not None:
        command.extend(["--lidar-directory", str(args.lidar_directory)])
    if args.lidar_manifest is not None:
        command.extend(["--lidar-manifest", str(args.lidar_manifest)])
    if args.dataset_id is not None:
        command.extend(["--dataset-id", args.dataset_id])
    if args.problem_id is not None:
        command.extend(["--problem-id", args.problem_id])
    try:
        problem = build_kitti360_camera_lidar_problem(
            args.sequence_path,
            args.depth_provider,
            calibration_root=args.calibration_root,
            lidar_directory=args.lidar_directory,
            lidar_manifest_path=args.lidar_manifest,
            camera_stream=args.camera_stream,
            split_id=args.split_id,
            dataset_id=args.dataset_id,
            problem_id=args.problem_id,
            rotation_bound_deg=args.rotation_bound_deg,
            translation_bound_m=args.translation_bound_m,
            command=tuple(command),
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    problem.save(args.output)
    _emit(
        {
            "status": "ok",
            "problem_id": problem.problem_id,
            "dataset_id": problem.dataset_id,
            "sequence_id": problem.sequence_id,
            "frame_count": len(problem.observations),
            "depth_provider_sha256": problem.depth_provider_sha256,
            "output": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_build_probabilistic_correspondence(
    args: argparse.Namespace,
) -> int:
    from calibrex.core.camera_lidar_correspondence_export import (
        build_probabilistic_correspondence_artifact,
    )

    command = [
        "calibrex",
        "camera-lidar",
        "build-probabilistic-correspondence",
        str(args.export_manifest),
        "--output",
        str(args.output),
    ]
    try:
        artifact = build_probabilistic_correspondence_artifact(
            args.export_manifest,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "artifact_id": artifact.artifact_id,
            "dataset_id": artifact.dataset_id,
            "frame_count": len(artifact.frames),
            "correspondence_count": sum(len(frame.correspondences) for frame in artifact.frames),
            "provider": artifact.provider.provider,
            "output": str(args.output),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_build_a2d2_problem(
    args: argparse.Namespace,
) -> int:
    from calibrex.data.a2d2_camera_lidar_problem import build_a2d2_camera_lidar_problem

    command = [
        "calibrex",
        "camera-lidar",
        "build-a2d2-problem",
        str(args.data_directory),
        str(args.depth_provider),
        "--lidar-output-directory",
        str(args.lidar_output_directory),
        "--lidar-manifest-output",
        str(args.lidar_manifest_output),
        "--output",
        str(args.output),
    ]
    try:
        problem = build_a2d2_camera_lidar_problem(
            args.data_directory,
            args.depth_provider,
            output_lidar_directory=args.lidar_output_directory,
            generated_manifest_path=args.lidar_manifest_output,
            command=command,
            problem_id=(args.problem_id or "a2d2-frontleft-preregistered-d2d"),
            rotation_bound_deg=args.rotation_bound_deg,
        )
        problem.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "problem_id": problem.problem_id,
            "dataset_id": problem.dataset_id,
            "frame_count": len(problem.observations),
            "depth_provider_sha256": problem.depth_provider_sha256,
            "lidar_manifest": str(args.lidar_manifest_output),
            "output": str(args.output),
            "accuracy_limitation": ("A2D2 source points are pre-registered into the camera view"),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_benchmark_rotation(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_rotation_benchmark import run_borer_rotation_benchmark
    from calibrex.visualization.bullseye import write_bullseye_plot

    if args.required_hit_rate is not None and not 0.0 <= args.required_hit_rate <= 1.0:
        _die("--required-hit-rate must be in [0, 1]")
    command = (
        f"calibrex camera-lidar benchmark-rotation {args.problem} {args.protocol} "
        f"--trace-dir {args.trace_dir} --definition-output "
        f"{args.definition_output} --output {args.output} --workers {args.workers}"
    )
    if args.resume:
        command += " --resume"
    try:
        definition, benchmark = run_borer_rotation_benchmark(
            args.problem,
            args.protocol,
            trace_directory=args.trace_dir,
            command=command,
            bootstrap_samples=args.bootstrap_samples,
            workers=args.workers,
            resume=args.resume,
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    definition.save(args.definition_output)
    benchmark.save(args.output)
    bullseye_output = args.bullseye_output or args.output.with_name(
        f"{args.output.stem}_bullseye.svg"
    )
    bullseye_artifact_output = args.bullseye_artifact_output or args.output.with_name(
        f"{args.output.stem}_bullseye.json"
    )
    try:
        write_bullseye_plot(
            args.problem,
            args.protocol,
            args.trace_dir,
            svg_path=bullseye_output,
            artifact_path=bullseye_artifact_output,
            command=tuple(command.split()),
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    summary = benchmark.method_summaries["native_borer_d2d_rotation"]
    hit_rate = summary.metrics["hit"].distribution.mean
    gate_passed = (
        hit_rate is not None
        and args.required_hit_rate is not None
        and hit_rate >= args.required_hit_rate
    )
    _emit(
        {
            "status": "ok",
            "definition": str(args.definition_output),
            "benchmark": str(args.output),
            "trace_directory": str(args.trace_dir),
            "bullseye": str(bullseye_output),
            "bullseye_artifact": str(bullseye_artifact_output),
            "trial_count": summary.trial_count,
            "success_count": summary.success_count,
            "failure_count": summary.failure_count,
            "failure_rate": summary.failure_rate,
            "hit_rate": hit_rate,
            "required_hit_rate": args.required_hit_rate,
            "gate_evaluated": args.required_hit_rate is not None,
            "gate_passed": gate_passed,
        },
        args.json,
    )
    if args.required_hit_rate is not None and not gate_passed:
        return 2
    return 0


def _cmd_demo_kitti_six_dof(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_six_dof_benchmark import ProjectionBackend
    from calibrex.pipelines.public_camera_lidar_demo import run_public_camera_lidar_six_dof_demo
    from calibrex.solvers.borer_six_dof_solver import BorerSixDofOptions

    try:
        demo = run_public_camera_lidar_six_dof_demo(
            args.sequence, args.depth_provider, output_directory=args.output_dir,
            candidate_backend=cast(ProjectionBackend, args.candidate_backend),
            candidate_frame_workers=args.candidate_frame_workers,
            repetitions=args.repetitions,
            reuse_verified_inputs=args.reuse_verified_inputs,
            cuda_cache_bytes=(
                args.cuda_cache_mib * 1024 * 1024 if args.cuda_cache_mib is not None else None
            ),
            options=BorerSixDofOptions(max_evaluations=args.max_evaluations),
            rotation_offset_deg=tuple(args.rotation_offset_deg),
            translation_offset_m=tuple(args.translation_offset_m),
            command=["calibrex", *args.invoked_argv],
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit({
        "status": "success" if demo.successful else "incomplete",
        "numerical_parity": demo.numerical_parity,
        "report": str(demo.report_path),
        "benchmark": str(demo.report_path.parent / "comparison.benchmark.json"),
        "trials": [
            trial.model_dump(mode="json", exclude_none=True) for trial in demo.benchmark.trials
        ],
        "timing_summaries": {
            method_id: {
                name: summary.metrics[name].distribution.model_dump(mode="json")
                for name in ("solve_seconds", "pipeline_seconds")
            } for method_id, summary in demo.benchmark.method_summaries.items()
        },
    }, args.json)
    return 0 if demo.successful else 2


def _cmd_demo_kitti_six_dof_sweep(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_six_dof_benchmark import ProjectionBackend
    from calibrex.evaluation.public_six_dof_sweep import run_public_six_dof_sweep
    from calibrex.solvers.borer_six_dof_solver import BorerSixDofOptions

    try:
        sweep = run_public_six_dof_sweep(
            args.sequence, args.depth_provider, output_directory=args.output_dir,
            candidate_backend=cast(ProjectionBackend, args.candidate_backend),
            candidate_frame_workers=args.candidate_frame_workers,
            workers=args.workers, repetitions=args.repetitions,
            reuse_verified_inputs=args.reuse_verified_inputs,
            rotation_deg=args.rotation_deg, translation_m=args.translation_m,
            cuda_cache_bytes=(
                args.cuda_cache_mib * 1024 * 1024 if args.cuda_cache_mib is not None else None
            ),
            options=BorerSixDofOptions(max_evaluations=args.max_evaluations),
            command=["calibrex", *args.invoked_argv],
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit({
        "status": "success" if sweep.successful else "incomplete",
        "report": str(sweep.report_path),
        "benchmark": str(sweep.report_path.parent / "sweep.benchmark.json"),
        "elapsed_seconds": sweep.elapsed_seconds,
        "workers": args.workers,
        "candidate_frame_workers": args.candidate_frame_workers,
        "cases": {
            case_id: {
                "status": "success" if demo.successful else "incomplete",
                "numerical_parity": demo.numerical_parity,
                "report": str(demo.report_path),
            } for case_id, demo in sweep.demos.items()
        },
    }, args.json)
    return 0 if sweep.successful else 2


def _cmd_camera_lidar_estimate_six_dof(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_six_dof_benchmark import ProjectionBackend
    from calibrex.pipelines.camera_lidar_six_dof import run_camera_lidar_six_dof_estimate
    from calibrex.solvers.borer_depth_to_depth_solver import DepthToDepthOptions
    from calibrex.solvers.borer_six_dof_solver import BorerSixDofOptions

    try:
        options = BorerSixDofOptions(
            rotation_bound_deg=args.rotation_bound_deg,
            translation_bound_m=args.translation_bound_m,
            initial_rotation_step_deg=args.initial_rotation_step_deg,
            initial_translation_step_m=args.initial_translation_step_m,
            minimum_rotation_step_deg=args.minimum_rotation_step_deg,
            minimum_translation_step_m=args.minimum_translation_step_m,
            max_evaluations=args.max_evaluations,
            improvement_tolerance=args.improvement_tolerance,
            objective=args.objective,
            d2d=DepthToDepthOptions(
                histogram_bins=args.histogram_bins, min_visible_points=args.min_visible_points,
            ),
        )
        result = run_camera_lidar_six_dof_estimate(
            args.problem,
            options=options,
            projection_backend=cast(ProjectionBackend, args.projection_backend),
            cuda_cache_bytes=(
                args.cuda_cache_mib * 1024 * 1024 if args.cuda_cache_mib is not None else None
            ),
            initial_result_path=args.initial_result,
            frame_workers=args.frame_workers,
            holdout_frame_ids=args.holdout_frame_id,
            command=["calibrex", *args.invoked_argv],
        )
        result.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    solver = result.run.provenance["solver_result"]
    _emit(
        {
            "status": solver["status"],
            "run_status": result.run.status,
            "quality_grade": result.quality.grade,
            "result": str(args.output),
            "projection_backend": result.run.provenance["projection_backend"],
            "frame_workers": result.run.provenance["configuration"]["frame_workers"],
            "effective_frame_workers": (
                result.run.provenance["configuration"]["effective_frame_workers"]
            ),
            "projection_transfer_statistics": (
                result.run.provenance["projection_transfer_statistics"]
            ),
            "evaluation_count": solver["evaluation_count"],
            "stopping_reason": solver["stopping_reason"],
            "final_mutual_information": result.metrics["final_d2d_mutual_information"].train,
            "holdout_mutual_information": result.metrics["final_d2d_mutual_information"].holdout,
            "timing_seconds": result.run.provenance["timing_seconds"],
        },
        args.json,
    )
    return 0 if solver["status"] == "converged" else 2


def _cmd_camera_lidar_benchmark_six_dof(args: argparse.Namespace) -> int:
    from calibrex.evaluation.borer_six_dof_benchmark import (
        ProjectionBackend,
        run_borer_six_dof_benchmark,
    )

    if args.required_hit_rate is not None and not 0.0 <= args.required_hit_rate <= 1.0:
        _die("--required-hit-rate must be in [0, 1]")
    command = (
        f"calibrex camera-lidar benchmark-six-dof {args.problem} {args.protocol} "
        f"--trace-dir {args.trace_dir} --definition-output "
        f"{args.definition_output} --output {args.output} --workers {args.workers} "
        f"--projection-backend {args.projection_backend} "
        f"--bootstrap-samples {args.bootstrap_samples}"
    )
    if args.cuda_cache_mib is not None:
        command += f" --cuda-cache-mib {args.cuda_cache_mib}"
    if args.required_hit_rate is not None:
        command += f" --required-hit-rate {args.required_hit_rate}"
    if args.resume:
        command += " --resume"
    try:
        definition, benchmark = run_borer_six_dof_benchmark(
            args.problem,
            args.protocol,
            trace_directory=args.trace_dir,
            command=command,
            bootstrap_samples=args.bootstrap_samples,
            workers=args.workers,
            resume=args.resume,
            projection_backend=cast(
                ProjectionBackend,
                args.projection_backend,
            ),
            cuda_cache_bytes=(
                args.cuda_cache_mib * 1024 * 1024 if args.cuda_cache_mib is not None else None
            ),
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    definition.save(args.definition_output)
    benchmark.save(args.output)
    summary = benchmark.method_summaries["native_borer_d2d_six_dof"]
    hit_rate = summary.metrics["hit"].distribution.mean
    gate_passed = (
        hit_rate is not None
        and args.required_hit_rate is not None
        and hit_rate >= args.required_hit_rate
    )
    _emit(
        {
            "status": "ok",
            "definition": str(args.definition_output),
            "benchmark": str(args.output),
            "trace_directory": str(args.trace_dir),
            "projection_backend": args.projection_backend,
            "trial_count": summary.trial_count,
            "success_count": summary.success_count,
            "failure_count": summary.failure_count,
            "failure_rate": summary.failure_rate,
            "hit_rate": hit_rate,
            "required_hit_rate": args.required_hit_rate,
            "gate_evaluated": args.required_hit_rate is not None,
            "gate_passed": gate_passed,
        },
        args.json,
    )
    if args.required_hit_rate is not None and not gate_passed:
        return 2
    return 0


def _cmd_camera_lidar_refine_probabilistic_pnp(
    args: argparse.Namespace,
) -> int:
    from calibrex.core.camera_lidar_artifacts import load_camera_lidar_problem
    from calibrex.core.provenance import sha256_path
    from calibrex.solvers.opencv_probabilistic_pnp_adapter import (
        OpenCvProbabilisticPnpAdapter,
        OpenCvProbabilisticPnpOptions,
    )

    options = OpenCvProbabilisticPnpOptions(
        minimum_confidence=args.minimum_confidence,
        minimum_correspondences=args.minimum_correspondences,
        ransac_reprojection_threshold_px=(args.ransac_reprojection_threshold_px),
        ransac_confidence=args.ransac_confidence,
        ransac_iterations=args.ransac_iterations,
        mahalanobis_inlier_threshold=args.mahalanobis_inlier_threshold,
        random_seed=args.random_seed,
    )
    command = [
        "calibrex",
        "camera-lidar",
        "refine-probabilistic-pnp",
        str(args.correspondence_artifact),
        args.frame_id,
        "--output",
        str(args.output),
    ]
    initial_transform = None
    initialization_digest = None
    if args.initial_problem is not None:
        try:
            problem = load_camera_lidar_problem(args.initial_problem)
        except (OSError, ValueError) as exc:
            raise CalibrexError(str(exc)) from exc
        initial_transform = problem.initial_transform_camera_lidar.as_se3()
        initialization_digest = sha256_path(args.initial_problem)
        if initialization_digest is None:
            raise CalibrexError(f"initialization problem is not readable: {args.initial_problem}")
        command.extend(["--initial-problem", str(args.initial_problem)])
    try:
        result = OpenCvProbabilisticPnpAdapter().solve_artifact(
            args.correspondence_artifact,
            args.frame_id,
            options,
            initial_transform_camera_lidar=initial_transform,
            initialization_artifact_sha256=initialization_digest,
        )
        artifact = result.to_artifact(
            result_id=(args.result_id or f"{result.artifact_id}-{args.frame_id}-opencv-pnp"),
            options=options,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": result.status,
            "result": str(args.output),
            "frame_id": args.frame_id,
            "selected_correspondence_count": (result.selected_correspondence_count),
            "ransac_inlier_count": result.ransac_inlier_count,
            "probabilistic_inlier_count": (result.probabilistic_inlier_count),
            "weighted_reprojection_rmse_px": (result.weighted_reprojection_rmse_px),
            "ransac_inlier_reprojection_rmse_px": (result.ransac_inlier_reprojection_rmse_px),
            "mean_mahalanobis_error": result.mean_mahalanobis_error,
        },
        args.json,
    )
    return 0 if result.status == "converged" else 2


def _cmd_camera_lidar_refine_probabilistic_pnp_aggregate(
    args: argparse.Namespace,
) -> int:
    from calibrex.core.camera_lidar_artifacts import load_camera_lidar_problem
    from calibrex.core.camera_lidar_initializer_calibration import (
        load_camera_lidar_initializer_calibration,
    )
    from calibrex.core.probabilistic_correspondence import load_probabilistic_correspondence
    from calibrex.core.provenance import sha256_path
    from calibrex.evaluation.camera_lidar_initializer_calibration import (
        initializer_options_from_camera_lidar_calibration,
    )
    from calibrex.solvers.opencv_probabilistic_pnp_adapter import (
        OpenCvProbabilisticPnpAdapter,
        OpenCvProbabilisticPnpOptions,
    )

    initializer_calibration_id = None
    initializer_calibration_digest = None
    try:
        if args.initializer_calibration is not None:
            custom_option_flags = (
                args.minimum_confidence != 0.25
                or args.minimum_correspondences != 6
                or args.minimum_frame_correspondences != 4
                or args.minimum_frames != 2
                or args.ransac_reprojection_threshold_px != 4.0
                or args.ransac_confidence != 0.999
                or args.ransac_iterations != 1000
                or args.mahalanobis_inlier_threshold != 3.0
            )
            if custom_option_flags:
                raise ValueError(
                    "initializer calibration cannot be combined with solver option overrides"
                )
            if args.initial_problem is not None:
                raise ValueError(
                    "locked aggregate PnP forbids an initial problem because "
                    "development calibration used no pose initializer"
                )
            calibration = load_camera_lidar_initializer_calibration(args.initializer_calibration)
            correspondence = load_probabilistic_correspondence(args.correspondence_artifact)
            if correspondence.provider != calibration.provider:
                raise ValueError("correspondence provider identity differs from initializer lock")
            allowed_dataset_ids = {
                calibration.dataset_id,
                *calibration.evaluation_dataset_ids_excluded,
            }
            if correspondence.dataset_id not in allowed_dataset_ids:
                raise ValueError("correspondence dataset was not prespecified by initializer lock")
            options = initializer_options_from_camera_lidar_calibration(
                calibration,
                random_seed=args.random_seed,
            )
            initializer_calibration_id = calibration.calibration_id
            initializer_calibration_digest = sha256_path(args.initializer_calibration)
            if initializer_calibration_digest is None:
                raise ValueError(
                    "initializer calibration artifact is not readable: "
                    f"{args.initializer_calibration}"
                )
        else:
            options = OpenCvProbabilisticPnpOptions(
                minimum_confidence=args.minimum_confidence,
                minimum_correspondences=args.minimum_correspondences,
                minimum_frame_correspondences=(args.minimum_frame_correspondences),
                minimum_frames=args.minimum_frames,
                ransac_reprojection_threshold_px=(args.ransac_reprojection_threshold_px),
                ransac_confidence=args.ransac_confidence,
                ransac_iterations=args.ransac_iterations,
                mahalanobis_inlier_threshold=(args.mahalanobis_inlier_threshold),
                random_seed=args.random_seed,
            )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    command = [
        "calibrex",
        "camera-lidar",
        "refine-probabilistic-pnp-aggregate",
        str(args.correspondence_artifact),
        "--output",
        str(args.output),
    ]
    if args.initializer_calibration is not None:
        command.extend(
            [
                "--initializer-calibration",
                str(args.initializer_calibration),
                "--random-seed",
                str(options.random_seed),
            ]
        )
    else:
        command.extend(
            [
                "--minimum-confidence",
                str(options.minimum_confidence),
                "--minimum-correspondences",
                str(options.minimum_correspondences),
                "--minimum-frame-correspondences",
                str(options.minimum_frame_correspondences),
                "--minimum-frames",
                str(options.minimum_frames),
                "--ransac-reprojection-threshold-px",
                str(options.ransac_reprojection_threshold_px),
                "--ransac-confidence",
                str(options.ransac_confidence),
                "--ransac-iterations",
                str(options.ransac_iterations),
                "--mahalanobis-inlier-threshold",
                str(options.mahalanobis_inlier_threshold),
                "--random-seed",
                str(options.random_seed),
            ]
        )
    if args.result_id is not None:
        command.extend(["--result-id", args.result_id])
    initial_transform = None
    initialization_digest = None
    if args.initial_problem is not None:
        try:
            problem = load_camera_lidar_problem(args.initial_problem)
        except (OSError, ValueError) as exc:
            raise CalibrexError(str(exc)) from exc
        initial_transform = problem.initial_transform_camera_lidar.as_se3()
        initialization_digest = sha256_path(args.initial_problem)
        if initialization_digest is None:
            raise CalibrexError(f"initialization problem is not readable: {args.initial_problem}")
        command.extend(["--initial-problem", str(args.initial_problem)])
    try:
        result = OpenCvProbabilisticPnpAdapter().solve_artifact_aggregate(
            args.correspondence_artifact,
            options,
            initial_transform_camera_lidar=initial_transform,
            initialization_artifact_sha256=initialization_digest,
            initializer_calibration_id=initializer_calibration_id,
            initializer_calibration_sha256=initializer_calibration_digest,
        )
        artifact = result.to_artifact(
            result_id=(args.result_id or f"{result.artifact_id}-aggregate-opencv-pnp"),
            options=options,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": result.status,
            "result": str(args.output),
            "frame_id": result.frame_id,
            "source_frame_ids": list(result.source_frame_ids),
            "frame_selection_rule_id": result.frame_selection_rule_id,
            "initializer_calibration_id": initializer_calibration_id,
            "initializer_calibration_sha256": initializer_calibration_digest,
            "selected_correspondence_count": (result.selected_correspondence_count),
            "ransac_inlier_count": result.ransac_inlier_count,
            "probabilistic_inlier_count": (result.probabilistic_inlier_count),
            "weighted_reprojection_rmse_px": (result.weighted_reprojection_rmse_px),
            "ransac_inlier_reprojection_rmse_px": (result.ransac_inlier_reprojection_rmse_px),
            "mean_mahalanobis_error": result.mean_mahalanobis_error,
        },
        args.json,
    )
    return 0 if result.status == "converged" else 2


def _cmd_camera_lidar_refine_probabilistic_multiframe(
    args: argparse.Namespace,
) -> int:
    from calibrex.core.camera_lidar_confidence_calibration import (
        load_camera_lidar_confidence_calibration,
    )
    from calibrex.evaluation.camera_lidar_confidence_calibration import (
        refinement_options_from_camera_lidar_confidence_calibration,
    )
    from calibrex.evaluation.probabilistic_camera_lidar_run import (
        run_probabilistic_camera_lidar_refinement,
    )
    from calibrex.solvers.probabilistic_camera_lidar_refiner import (
        ProbabilisticCameraLidarRefinementOptions,
    )

    try:
        if args.confidence_calibration is not None:
            custom_option_flags = (
                args.minimum_confidence != 0.25
                or args.holdout_ratio != 0.25
                or args.minimum_train_correspondences != 24
                or args.minimum_holdout_correspondences != 8
                or args.max_evaluations != 400
                or args.minimum_absolute_train_objective_improvement != 1.0e-6
                or args.minimum_relative_train_objective_improvement != 1.0e-4
                or args.maximum_train_correspondence_loss_fraction != 0.05
                or args.maximum_accepted_bound_fraction != 0.95
                or args.without_covariance
                or args.without_outlier_probability
                or args.without_reliability
            )
            if custom_option_flags:
                raise ValueError(
                    "confidence calibration cannot be combined with solver option overrides"
                )
            calibration = load_camera_lidar_confidence_calibration(args.confidence_calibration)
            options = refinement_options_from_camera_lidar_confidence_calibration(
                calibration,
                split_seed=args.split_seed,
            )
        else:
            options = ProbabilisticCameraLidarRefinementOptions(
                holdout_ratio=args.holdout_ratio,
                split_seed=args.split_seed,
                minimum_confidence=args.minimum_confidence,
                minimum_train_correspondences=(args.minimum_train_correspondences),
                minimum_holdout_correspondences=(args.minimum_holdout_correspondences),
                max_evaluations=args.max_evaluations,
                minimum_absolute_train_objective_improvement=(
                    args.minimum_absolute_train_objective_improvement
                ),
                minimum_relative_train_objective_improvement=(
                    args.minimum_relative_train_objective_improvement
                ),
                maximum_train_correspondence_loss_fraction=(
                    args.maximum_train_correspondence_loss_fraction
                ),
                maximum_accepted_bound_fraction=(args.maximum_accepted_bound_fraction),
                use_covariance=not args.without_covariance,
                use_outlier_probability=not args.without_outlier_probability,
                use_reliability=not args.without_reliability,
            )
        command = [
            "calibrex",
            "camera-lidar",
            "refine-probabilistic-multiframe",
            str(args.correspondence_artifact),
            str(args.initial_problem),
            "--output",
            str(args.output),
            "--split-seed",
            str(args.split_seed),
        ]
        if args.initial_trace is not None:
            command.extend(["--initial-trace", str(args.initial_trace)])
        if args.confidence_calibration is not None:
            command.extend(["--confidence-calibration", str(args.confidence_calibration)])
        result = run_probabilistic_camera_lidar_refinement(
            args.correspondence_artifact,
            args.initial_problem,
            initialization_trace_path=args.initial_trace,
            confidence_calibration_path=args.confidence_calibration,
            result_id=args.result_id,
            options=options,
            command=command,
        )
        result.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    acceptance = result.acceptance
    if acceptance is None:
        raise CalibrexError(
            "new probabilistic refinement output is missing its acceptance decision"
        )
    _emit(
        {
            "status": result.status,
            "result": str(args.output),
            "initialization_source": result.initialization_source,
            "initialization_trace_id": result.initialization_trace_id,
            "initialization_trace_status": result.initialization_trace_status,
            "initialization_trace_hit": result.initialization_trace_hit,
            "confidence_calibration_id": (result.provenance.confidence_calibration_id),
            "candidate_accepted": acceptance.accepted,
            "selected_source": acceptance.selected_source,
            "acceptance_reasons": acceptance.reasons,
            "train_frame_count": len(result.train_frame_ids),
            "holdout_frame_count": len(result.holdout_frame_ids),
            "initial_holdout_rmse_px": (
                result.initial_holdout_evaluation.weighted_reprojection_rmse_px
            ),
            "final_holdout_rmse_px": (
                result.final_holdout_evaluation.weighted_reprojection_rmse_px
            ),
            "final_rotation_error_deg": result.final_rotation_error_deg,
            "final_translation_error_m": result.final_translation_error_m,
            "use_covariance": result.options["use_covariance"],
            "use_outlier_probability": (result.options["use_outlier_probability"]),
            "use_reliability": result.options["use_reliability"],
        },
        args.json,
    )
    return 0 if result.status == "converged" else 2


def _cmd_camera_lidar_diagnose_probabilistic_correspondence(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.camera_lidar_correspondence_quality import (
        analyze_camera_lidar_correspondence_quality,
    )

    command = [
        "calibrex",
        "camera-lidar",
        "diagnose-probabilistic-correspondence",
        str(args.correspondence_artifact),
        str(args.refinement_result),
        "--pose-role",
        args.pose_role,
        "--minimum-frame-correspondences",
        str(args.minimum_frame_correspondences),
        "--output",
        str(args.output),
    ]
    try:
        report = analyze_camera_lidar_correspondence_quality(
            args.correspondence_artifact,
            args.refinement_result,
            pose_role=args.pose_role,
            report_id=args.report_id,
            minimum_frame_correspondences=args.minimum_frame_correspondences,
            command=command,
        )
        report.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "grade": report.summary.grade,
            "report": str(args.output),
            "report_id": report.report_id,
            "pose_role": report.pose_role,
            "frame_count": report.summary.frame_count,
            "accepted_correspondence_count": (report.summary.accepted_correspondence_count),
            "accepted_correspondence_rate": (report.summary.accepted_correspondence_rate),
            "aggregate_information_rank": (report.summary.aggregate_observability.rank),
            "gate_reasons": report.summary.gate_reasons,
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_calibrate_probabilistic_confidence(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.camera_lidar_confidence_calibration import (
        calibrate_camera_lidar_confidence,
    )

    try:
        thresholds = tuple(
            float(value.strip()) for value in args.thresholds.split(",") if value.strip()
        )
        calibration_seeds = tuple(
            int(value.strip()) for value in args.calibration_split_seeds.split(",") if value.strip()
        )
        evaluation_seeds = tuple(
            int(value.strip()) for value in args.evaluation_split_seeds.split(",") if value.strip()
        )
    except ValueError as exc:
        raise CalibrexError(f"invalid confidence calibration list: {exc}") from exc
    excluded_dataset_ids = [
        value.strip() for value in args.excluded_evaluation_dataset_ids.split(",") if value.strip()
    ]
    command = [
        "calibrex",
        "camera-lidar",
        "calibrate-probabilistic-confidence",
        str(args.correspondence_artifact),
        str(args.initial_problem),
        "--output",
        str(args.output),
        "--thresholds",
        args.thresholds,
        "--calibration-split-seeds",
        args.calibration_split_seeds,
        "--evaluation-split-seeds",
        args.evaluation_split_seeds,
        "--holdout-ratio",
        str(args.holdout_ratio),
        "--minimum-train-correspondences",
        str(args.minimum_train_correspondences),
        "--minimum-holdout-correspondences",
        str(args.minimum_holdout_correspondences),
        "--minimum-frame-correspondences",
        str(args.minimum_frame_correspondences),
        "--minimum-frame-support-rate",
        str(args.minimum_frame_support_rate),
        "--minimum-full-rank-frame-rate",
        str(args.minimum_full_rank_frame_rate),
        "--development-reprojection-inlier-threshold-px",
        str(args.development_reprojection_inlier_threshold_px),
        "--minimum-geometric-inlier-rate",
        str(args.minimum_geometric_inlier_rate),
        "--minimum-frame-geometric-inlier-count",
        str(args.minimum_frame_geometric_inlier_count),
        "--minimum-frame-geometric-support-rate",
        str(args.minimum_frame_geometric_support_rate),
        "--excluded-evaluation-dataset-ids",
        args.excluded_evaluation_dataset_ids,
    ]
    try:
        calibration = calibrate_camera_lidar_confidence(
            args.correspondence_artifact,
            args.initial_problem,
            thresholds=thresholds,
            calibration_split_seeds=calibration_seeds,
            evaluation_split_seeds=evaluation_seeds,
            holdout_ratio=args.holdout_ratio,
            minimum_train_correspondences=args.minimum_train_correspondences,
            minimum_holdout_correspondences=(args.minimum_holdout_correspondences),
            minimum_frame_correspondences=args.minimum_frame_correspondences,
            minimum_frame_support_rate=args.minimum_frame_support_rate,
            minimum_full_rank_frame_rate=args.minimum_full_rank_frame_rate,
            development_reprojection_inlier_threshold_px=(
                args.development_reprojection_inlier_threshold_px
            ),
            minimum_geometric_inlier_rate=args.minimum_geometric_inlier_rate,
            minimum_frame_geometric_inlier_count=(args.minimum_frame_geometric_inlier_count),
            minimum_frame_geometric_support_rate=(args.minimum_frame_geometric_support_rate),
            evaluation_dataset_ids_excluded=excluded_dataset_ids,
            calibration_id=args.calibration_id,
            command=command,
        )
        calibration.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": calibration.status,
            "calibration": str(args.output),
            "calibration_id": calibration.calibration_id,
            "development_dataset_id": calibration.dataset_id,
            "selected_minimum_confidence": (calibration.selected_minimum_confidence),
            "passing_thresholds": [
                item.minimum_confidence for item in calibration.candidates if item.gate_pass
            ],
            "evaluation_dataset_ids_excluded": (calibration.evaluation_dataset_ids_excluded),
            "release_sota_claim_allowed": calibration.release_sota_claim_allowed,
        },
        args.json,
    )
    return 0 if calibration.status == "locked" else 2


def _cmd_camera_lidar_compare_probabilistic_provider_support(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.camera_lidar_provider_support_comparison import (
        compare_camera_lidar_provider_support,
    )

    command = [
        "calibrex",
        "camera-lidar",
        "compare-probabilistic-provider-support",
        *(str(path) for path in args.confidence_calibrations),
        "--output",
        str(args.output),
    ]
    if args.comparison_id is not None:
        command.extend(["--comparison-id", args.comparison_id])
    try:
        comparison = compare_camera_lidar_provider_support(
            args.confidence_calibrations,
            comparison_id=args.comparison_id,
            command=command,
        )
        comparison.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    leader = next(
        item
        for item in comparison.candidates
        if item.candidate_id == comparison.diagnostic_leader_candidate_id
    )
    _emit(
        {
            "status": comparison.status,
            "comparison": str(args.output),
            "comparison_id": comparison.comparison_id,
            "selected_candidate_id": comparison.selected_candidate_id,
            "diagnostic_leader_candidate_id": (comparison.diagnostic_leader_candidate_id),
            "diagnostic_leader_provider_version": leader.provider.version,
            "diagnostic_leader_threshold": (leader.diagnostic.minimum_confidence),
            "diagnostic_leader_worst_split_geometric_inliers": (
                leader.worst_split_geometric_inlier_count
            ),
            "evaluation_dataset_ids_excluded": (
                comparison.protocol.evaluation_dataset_ids_excluded
            ),
            "release_sota_claim_allowed": comparison.release_sota_claim_allowed,
        },
        args.json,
    )
    return 0 if comparison.status == "locked" else 2


def _cmd_camera_lidar_calibrate_probabilistic_pnp_initializer(
    args: argparse.Namespace,
) -> int:
    from calibrex.core.camera_lidar_initializer_calibration import (
        CameraLidarInitializerRecoveryGate,
    )
    from calibrex.evaluation.camera_lidar_initializer_calibration import (
        calibrate_camera_lidar_initializer,
    )

    try:
        confidence_thresholds = tuple(
            float(value.strip()) for value in args.confidence_thresholds.split(",") if value.strip()
        )
        reprojection_thresholds = tuple(
            float(value.strip())
            for value in args.ransac_reprojection_thresholds_px.split(",")
            if value.strip()
        )
        random_seeds = tuple(
            int(value.strip()) for value in args.random_seeds.split(",") if value.strip()
        )
        gate = CameraLidarInitializerRecoveryGate(
            rotation_error_max_deg=args.rotation_error_max_deg,
            translation_error_max_m=args.translation_error_max_m,
            minimum_selected_frame_count=(args.gate_minimum_selected_frame_count),
            minimum_selected_correspondence_count=(args.gate_minimum_selected_correspondence_count),
            minimum_ransac_inlier_count=(args.gate_minimum_ransac_inlier_count),
            maximum_ransac_inlier_reprojection_rmse_px=(args.gate_maximum_ransac_inlier_rmse_px),
            maximum_seed_rotation_delta_deg=(args.gate_maximum_seed_rotation_delta_deg),
            maximum_seed_translation_delta_m=(args.gate_maximum_seed_translation_delta_m),
        )
    except ValueError as exc:
        raise CalibrexError(f"invalid initializer calibration option: {exc}") from exc
    excluded_dataset_ids = [
        value.strip() for value in args.excluded_evaluation_dataset_ids.split(",") if value.strip()
    ]
    command = [
        "calibrex",
        "camera-lidar",
        "calibrate-probabilistic-pnp-initializer",
        str(args.correspondence_artifact),
        str(args.initial_problem),
        "--output",
        str(args.output),
        "--confidence-thresholds",
        args.confidence_thresholds,
        "--ransac-reprojection-thresholds-px",
        args.ransac_reprojection_thresholds_px,
        "--random-seeds",
        args.random_seeds,
        "--minimum-correspondences",
        str(args.minimum_correspondences),
        "--minimum-frame-correspondences",
        str(args.minimum_frame_correspondences),
        "--minimum-frames",
        str(args.minimum_frames),
        "--ransac-confidence",
        str(args.ransac_confidence),
        "--ransac-iterations",
        str(args.ransac_iterations),
        "--mahalanobis-inlier-threshold",
        str(args.mahalanobis_inlier_threshold),
        "--rotation-error-max-deg",
        str(args.rotation_error_max_deg),
        "--translation-error-max-m",
        str(args.translation_error_max_m),
        "--gate-minimum-selected-frame-count",
        str(args.gate_minimum_selected_frame_count),
        "--gate-minimum-selected-correspondence-count",
        str(args.gate_minimum_selected_correspondence_count),
        "--gate-minimum-ransac-inlier-count",
        str(args.gate_minimum_ransac_inlier_count),
        "--gate-maximum-ransac-inlier-rmse-px",
        str(args.gate_maximum_ransac_inlier_rmse_px),
        "--gate-maximum-seed-rotation-delta-deg",
        str(args.gate_maximum_seed_rotation_delta_deg),
        "--gate-maximum-seed-translation-delta-m",
        str(args.gate_maximum_seed_translation_delta_m),
        "--excluded-evaluation-dataset-ids",
        args.excluded_evaluation_dataset_ids,
    ]
    if args.calibration_id is not None:
        command.extend(["--calibration-id", args.calibration_id])
    try:
        calibration = calibrate_camera_lidar_initializer(
            args.correspondence_artifact,
            args.initial_problem,
            confidence_thresholds=confidence_thresholds,
            ransac_reprojection_thresholds_px=reprojection_thresholds,
            random_seeds=random_seeds,
            minimum_correspondences=args.minimum_correspondences,
            minimum_frame_correspondences=(args.minimum_frame_correspondences),
            minimum_frames=args.minimum_frames,
            ransac_confidence=args.ransac_confidence,
            ransac_iterations=args.ransac_iterations,
            mahalanobis_inlier_threshold=(args.mahalanobis_inlier_threshold),
            recovery_gate=gate,
            evaluation_dataset_ids_excluded=excluded_dataset_ids,
            calibration_id=args.calibration_id,
            command=command,
        )
        calibration.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    locked = calibration.locked_initializer_options
    _emit(
        {
            "status": calibration.status,
            "calibration": str(args.output),
            "calibration_id": calibration.calibration_id,
            "development_dataset_id": calibration.dataset_id,
            "candidate_count": len(calibration.candidates),
            "passing_candidate_count": sum(item.gate_pass for item in calibration.candidates),
            "selected_candidate_id": calibration.selected_candidate_id,
            "selected_minimum_confidence": (
                locked.minimum_confidence if locked is not None else None
            ),
            "selected_ransac_reprojection_threshold_px": (
                locked.ransac_reprojection_threshold_px if locked is not None else None
            ),
            "evaluation_dataset_ids_excluded": (calibration.evaluation_dataset_ids_excluded),
            "release_sota_claim_allowed": calibration.release_sota_claim_allowed,
        },
        args.json,
    )
    return 0 if calibration.status == "locked" else 2


def _cmd_camera_lidar_benchmark_probabilistic_ablation(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.probabilistic_refinement_ablation import (
        run_probabilistic_refinement_ablation,
    )

    try:
        seeds = tuple(int(value.strip()) for value in args.split_seeds.split(",") if value.strip())
    except ValueError as exc:
        raise CalibrexError("--split-seeds must contain integers") from exc
    command = (
        "calibrex camera-lidar benchmark-probabilistic-ablation "
        f"{args.correspondence_artifact} {args.initial_problem} "
        f"--result-dir {args.result_dir} --definition-output "
        f"{args.definition_output} --output {args.output} "
        f"--split-seeds {args.split_seeds}"
    )
    if args.initial_trace is not None:
        command += f" --initial-trace {args.initial_trace}"
    try:
        definition, benchmark = run_probabilistic_refinement_ablation(
            args.correspondence_artifact,
            args.initial_problem,
            initialization_trace_path=args.initial_trace,
            result_directory=args.result_dir,
            command=command,
            split_seeds=seeds,
            bootstrap_samples=args.bootstrap_samples,
        )
        definition.save(args.definition_output)
        benchmark.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "definition": str(args.definition_output),
            "benchmark": str(args.output),
            "result_directory": str(args.result_dir),
            "split_count": len(definition.protocol.splits),
            "method_count": len(definition.methods),
            "trial_count": len(definition.trials),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_benchmark_probabilistic_falsification(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.probabilistic_camera_lidar_falsification import (
        run_probabilistic_camera_lidar_falsification,
    )

    try:
        seeds = tuple(int(value.strip()) for value in args.split_seeds.split(",") if value.strip())
    except ValueError as exc:
        raise CalibrexError("--split-seeds must contain integers") from exc
    command = (
        "calibrex camera-lidar benchmark-probabilistic-falsification "
        f"{args.correspondence_artifact} {args.initial_problem} "
        f"--protocol {args.protocol} --output-dir {args.output_dir} "
        f"--split-seeds {args.split_seeds} "
        f"--known-bad-rotation-deg {args.known_bad_rotation_deg} "
        f"--known-bad-translation-m {args.known_bad_translation_m} "
        f"--known-bad-min-holdout-rmse-delta-px "
        f"{args.known_bad_min_holdout_rmse_delta_px} "
        f"--bootstrap-samples {args.bootstrap_samples}"
    )
    if args.initial_trace is not None:
        command += f" --initial-trace {args.initial_trace}"
    else:
        command += f" --trace-dir {args.trace_dir}"
    if args.max_final_holdout_rmse_px is not None:
        command += f" --max-final-holdout-rmse-px {args.max_final_holdout_rmse_px}"
    try:
        artifacts = run_probabilistic_camera_lidar_falsification(
            args.correspondence_artifact,
            args.initial_problem,
            initialization_trace_path=args.initial_trace,
            initialization_trace_directory=args.trace_dir,
            benchmark_protocol_path=args.protocol,
            output_directory=args.output_dir,
            command=command,
            split_seeds=seeds,
            known_bad_rotation_deg=args.known_bad_rotation_deg,
            known_bad_translation_m=args.known_bad_translation_m,
            known_bad_min_holdout_rmse_delta_px=(args.known_bad_min_holdout_rmse_delta_px),
            max_final_holdout_rmse_px=args.max_final_holdout_rmse_px,
            bootstrap_samples=args.bootstrap_samples,
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifacts.assessment.status,
            "assessment": str(artifacts.assessment_path),
            "benchmark": str(artifacts.benchmark_path),
            "definition": str(artifacts.definition_path),
            "evidence": str(artifacts.evidence_path),
            "failure_analysis": str(artifacts.failure_analysis_path),
            "bundle": str(artifacts.bundle_path),
            "verification": str(artifacts.verification_path),
            "verification_valid": artifacts.verification.valid,
            "result_count": len(artifacts.result_paths),
            "known_bad_case_count": len(artifacts.evidence.cases),
            "rotation_failure_count": (artifacts.failure_analysis.summary.rotation_failure_count),
            "translation_failure_count": (
                artifacts.failure_analysis.summary.translation_failure_count
            ),
        },
        args.json,
    )
    return 0 if artifacts.assessment.status == "pass" and artifacts.verification.valid else 2


def _cmd_camera_lidar_refine_continuous_time(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.continuous_time_camera_lidar_run import (
        run_continuous_time_camera_lidar_problem,
    )

    command = [
        "calibrex",
        "camera-lidar",
        "refine-continuous-time",
        str(args.problem),
        "--output",
        str(args.output),
    ]
    try:
        result = run_continuous_time_camera_lidar_problem(
            args.problem,
            result_id=args.result_id,
            command=command,
        )
        result.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": result.status,
            "result": str(args.output),
            "estimated_time_offset_sec": result.estimated_time_offset_sec,
            "final_rotation_error_deg": result.final_rotation_error_deg,
            "final_translation_error_m": result.final_translation_error_m,
            "final_time_offset_error_sec": (result.final_time_offset_error_sec),
            "time_observability_rank": result.time_observability_rank,
            "trajectory_model": result.trajectory_model,
            "train_correspondence_count": (
                result.final_train_evaluation.valid_correspondence_count
            ),
            "holdout_correspondence_count": (
                result.final_holdout_evaluation.valid_correspondence_count
            ),
            "initial_holdout_rmse_px": (
                result.initial_holdout_evaluation.weighted_reprojection_rmse_px
            ),
            "final_holdout_rmse_px": (
                result.final_holdout_evaluation.weighted_reprojection_rmse_px
            ),
        },
        args.json,
    )
    return 0 if result.status == "converged" else 2


def _cmd_camera_lidar_attach_continuous_trajectory(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.continuous_time_trajectory_adapter import (
        attach_recorded_body_trajectory,
    )

    command = [
        "calibrex",
        "camera-lidar",
        "attach-continuous-trajectory",
        str(args.problem),
        str(args.trajectory),
        "--output",
        str(args.output),
    ]
    try:
        problem = attach_recorded_body_trajectory(
            args.problem,
            args.trajectory,
            problem_id=args.problem_id,
            command=command,
        )
        problem.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "problem": str(args.output),
            "problem_id": problem.problem_id,
            "trajectory_pose_count": (
                len(problem.body_trajectory.poses) if problem.body_trajectory is not None else 0
            ),
            "trajectory_source_sha256": (
                problem.body_trajectory.source_sha256
                if problem.body_trajectory is not None
                else None
            ),
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_benchmark_continuous_time_ablation(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.continuous_time_camera_lidar_ablation import (
        run_continuous_time_camera_lidar_ablation,
    )

    try:
        seeds = tuple(int(value.strip()) for value in args.split_seeds.split(",") if value.strip())
    except ValueError as exc:
        raise CalibrexError("--split-seeds must contain integers") from exc
    command = (
        "calibrex camera-lidar benchmark-continuous-time-ablation "
        f"{args.problem} --result-dir {args.result_dir} "
        f"--definition-output {args.definition_output} --output "
        f"{args.output} --split-seeds {args.split_seeds}"
    )
    try:
        definition, benchmark = run_continuous_time_camera_lidar_ablation(
            args.problem,
            result_directory=args.result_dir,
            command=command,
            split_seeds=seeds,
            bootstrap_samples=args.bootstrap_samples,
        )
        definition.save(args.definition_output)
        benchmark.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "definition": str(args.definition_output),
            "benchmark": str(args.output),
            "result_directory": str(args.result_dir),
            "split_count": len(definition.protocol.splits),
            "method_count": len(definition.methods),
            "trial_count": len(definition.trials),
        },
        args.json,
    )
    return 0


def _cmd_gnss_lidar_rtk_slam(args: argparse.Namespace) -> int:
    from calibrex.evaluation.gnss_lidar_lever_arm import run_rtk_slam_lever_arm

    if len(args.bag) != len(args.rtk):
        _die("give exactly one --rtk per --bag")
    command = ["calibrex", "gnss-lidar", "rtk-slam"]
    for bag, rtk in zip(args.bag, args.rtk, strict=True):
        command += ["--bag", str(bag), "--rtk", str(rtk)]
    command += ["--calib", str(args.calib), "--output", str(args.output), "--topic", args.topic]
    if args.max_scans is not None:
        command += ["--max-scans", str(args.max_scans)]
    if args.max_seconds is not None:
        command += ["--max-seconds", str(args.max_seconds)]
    try:
        artifact = run_rtk_slam_lever_arm(
            list(zip(args.bag, args.rtk, strict=True)),
            args.calib,
            topic=args.topic,
            max_scans=args.max_scans,
            max_seconds=args.max_seconds,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_imu_lidar_livox(args: argparse.Namespace) -> int:
    from calibrex.data.livox_ros2 import MID360_T_LIDAR_IMU
    from calibrex.evaluation.imu_lidar_rotation import run_livox_imu_lidar_rotation

    command = ["calibrex", "imu-lidar", "livox", *(str(path) for path in args.bags)]
    command += ["--profile", args.profile, "--dataset-family", args.dataset_family]
    command += ["--dataset-license", args.dataset_license, "--output", str(args.output)]
    if args.no_mid360_reference:
        command.append("--no-mid360-reference")
    if args.max_scans is not None:
        command += ["--max-scans", str(args.max_scans)]
    try:
        artifact = run_livox_imu_lidar_rotation(
            args.bags,
            args.profile,
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            reference_rotation=None if args.no_mid360_reference else MID360_T_LIDAR_IMU[:3, :3],
            max_scans=args.max_scans,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_imu_lidar_joint(args: argparse.Namespace) -> int:
    from calibrex.check.estimators import detect_point_time
    from calibrex.data.livox_ros2 import LivoxStreamProfile
    from calibrex.evaluation.imu_lidar_rotation import ImuLidarRunOptions
    from calibrex.evaluation.lidar_imu_bag_calibration import (
        LidarImuBagOptions,
        calibrate_lidar_imu_bag,
    )
    from calibrex.evaluation.odometry_windows import WindowingOptions

    command = ["calibrex", "imu-lidar", "joint", str(args.bag)]
    command += ["--lidar-topic", args.lidar_topic, "--imu-topic", args.imu_topic]
    command += ["--acceleration-unit", args.acceleration_unit]
    command += ["--dataset-family", args.dataset_family, "--dataset-license", args.dataset_license]
    if args.max_seconds is not None:
        command += ["--max-seconds", str(args.max_seconds)]
    command += ["--max-rounds", str(args.max_rounds)]
    if args.fit_plane_backend != "numpy":
        command += ["--fit-plane-backend", args.fit_plane_backend]
    if args.imu_lowpass_hz is not None:
        command += ["--imu-lowpass-hz", str(args.imu_lowpass_hz)]
    command += ["--odometry-backend", args.odometry_backend]
    if args.resident_odometry:
        command += ["--resident-odometry"]
    windowing = WindowingOptions(odometry_backend=args.odometry_backend)
    odometry_settings = {
        "voxel_size_m": args.odometry_voxel_size_m,
        "local_map_scans": args.odometry_local_map_scans,
        "query_workers": args.odometry_query_workers,
        "geometry_quantum_m": args.odometry_geometry_quantum_m,
        "motion_translation_quantum_m": args.odometry_motion_translation_quantum_m,
        "motion_rotation_quantum_rad": args.odometry_motion_rotation_quantum_rad,
    }
    for name, value in odometry_settings.items():
        if value is not None:
            flag = "--odometry-" + name.replace("_", "-")
            command += [flag, str(value)]
    windowing = dataclasses.replace(
        windowing, odometry=dataclasses.replace(
            windowing.odometry, **{key: value for key, value in odometry_settings.items()
                                  if value is not None},
        ),
    )
    command += ["--output", str(args.output)]
    try:
        point_time = detect_point_time(args.bag, args.lidar_topic)
        profile = LivoxStreamProfile(
            name="joint",
            point_topic=args.lidar_topic,
            imu_topic=args.imu_topic,
            point_time_field=None if point_time is None else point_time[0],
            point_time_encoding="offset_s" if point_time is None else point_time[1],
            acceleration_unit=args.acceleration_unit,
        )
        artifact = calibrate_lidar_imu_bag(
            args.bag,
            profile,
            LidarImuBagOptions(
                max_rounds=args.max_rounds, imu_lowpass_hz=args.imu_lowpass_hz,
                fit_plane_backend=args.fit_plane_backend,
                resident_odometry=args.resident_odometry,
                rotation=ImuLidarRunOptions(windowing=windowing),
            ),
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            max_seconds=args.max_seconds,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "t_lidar_imu_translation_m": artifact.t_lidar_imu_translation_m,
            "t_lidar_imu_rotation_quat_xyzw": artifact.t_lidar_imu_rotation_quat_xyzw,
            "imu_clock_offset_s": artifact.imu_clock_offset_s,
            "blocks": {record.name: record.verdict for record in artifact.blocks},
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_imu_lidar_livox_translation(args: argparse.Namespace) -> int:
    from calibrex.core.imu_lidar_rotation import load_imu_lidar_rotation
    from calibrex.core.provenance import sha256_path
    from calibrex.data.livox_ros2 import MID360_T_LIDAR_IMU
    from calibrex.evaluation.imu_lidar_translation import run_livox_imu_lidar_translation

    command = ["calibrex", "imu-lidar", "livox-translation", *(str(path) for path in args.bags)]
    command += ["--profile", args.profile, "--rotation", str(args.rotation)]
    command += ["--dataset-family", args.dataset_family]
    command += ["--dataset-license", args.dataset_license, "--output", str(args.output)]
    if args.no_mid360_reference:
        command.append("--no-mid360-reference")
    if args.max_scans is not None:
        command += ["--max-scans", str(args.max_scans)]
    try:
        rotation = load_imu_lidar_rotation(args.rotation)
        artifact = run_livox_imu_lidar_translation(
            args.bags,
            args.profile,
            rotation,
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            rotation_artifact_sha256=sha256_path(args.rotation),
            reference_translation=None if args.no_mid360_reference else MID360_T_LIDAR_IMU[:3, 3],
            max_scans=args.max_scans,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_imu_lidar_trajectory(args: argparse.Namespace) -> int:
    from calibrex.evaluation.imu_trajectory import run_imu_trajectory_calibration

    if not args.rotation_only and args.output_translation is None:
        raise CalibrexError("--output-translation is required unless --rotation-only is given")
    command = ["calibrex", "imu-lidar", "trajectory", "--imu", str(args.imu)]
    command += ["--trajectory", str(args.trajectory)]
    command += ["--acceleration-unit", args.acceleration_unit]
    if args.mid360_reference:
        command.append("--mid360-reference")
    if args.rotation_only:
        command.append("--rotation-only")
    try:
        calibration = run_imu_trajectory_calibration(
            args.imu.read_text(encoding="utf-8"),
            args.trajectory.read_text(encoding="utf-8"),
            acceleration_unit=args.acceleration_unit,
            reference="mid360" if args.mid360_reference else "none",
            estimate_translation=not args.rotation_only,
            sequence_id=args.trajectory.stem,
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            command=command,
        )
        calibration.rotation.save(args.output_rotation)
        if calibration.translation is not None and args.output_translation is not None:
            calibration.translation.save(args.output_translation)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    statuses = [calibration.rotation.policy_status]
    payload: dict[str, Any] = {
        "rotation_status": calibration.rotation.policy_status,
        "rotation_artifact": str(args.output_rotation),
    }
    if calibration.translation is not None:
        statuses.append(calibration.translation.policy_status)
        payload["translation_status"] = calibration.translation.policy_status
        payload["translation_artifact"] = str(args.output_translation)
    _emit(payload, args.json)
    return 1 if "fail" in statuses else 0


def _cmd_camera_imu_rotation(args: argparse.Namespace) -> int:
    import numpy

    from calibrex.core.io import read_mapping
    from calibrex.evaluation.camera_imu_rotation import (
        CameraImuRunOptions,
        default_camera_evaluation_options,
        run_ros2_camera_imu_rotation,
    )
    from calibrex.evaluation.visual_rotation import CameraModel

    try:
        chain = read_mapping(args.camchain)
        entry = chain.get(args.camera)
        if not isinstance(entry, dict):
            raise ValueError(f"{args.camchain} has no camera {args.camera!r}")
        image_topic = args.image_topic or entry.get("rostopic")
        if not image_topic:
            raise ValueError("no --image-topic given and the camchain has no rostopic")
        reference_rotation = None
        reference = None
        if not args.no_reference and "T_cam_imu" in entry:
            reference_rotation = numpy.asarray(entry["T_cam_imu"], dtype=numpy.float64)[:3, :3]
            reference = (
                f"Kalibr camchain {args.camchain.name} {args.camera}: T_cam_imu, "
                f"timeshift_cam_imu {entry.get('timeshift_cam_imu', 'n/a')} s"
            )
        command = ["calibrex", "camera-imu", "rotation", *(str(bag) for bag in args.bags)]
        command += ["--camchain", str(args.camchain), "--camera", args.camera]
        command += ["--imu-topic", args.imu_topic, "--image-topic", str(image_topic)]
        command += ["--frame-stride", str(args.frame_stride)]
        if args.max_seconds is not None:
            command += ["--max-seconds", str(args.max_seconds)]
        if args.no_reference:
            command.append("--no-reference")
        evaluation = default_camera_evaluation_options()
        if args.observable_rotation_std_deg is not None:
            command += ["--observable-rotation-std-deg", str(args.observable_rotation_std_deg)]
            evaluation = dataclasses.replace(
                evaluation,
                solver=dataclasses.replace(
                    evaluation.solver, observable_rotation_std_deg=args.observable_rotation_std_deg
                ),
            )
        if args.min_window_rotation_deg is not None:
            command += ["--min-window-rotation-deg", str(args.min_window_rotation_deg)]
            evaluation = dataclasses.replace(
                evaluation, min_window_rotation_deg=args.min_window_rotation_deg
            )
        artifact = run_ros2_camera_imu_rotation(
            args.bags,
            image_topic=str(image_topic),
            imu_topic=args.imu_topic,
            camera=CameraModel.from_kalibr(entry),
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            acceleration_unit=args.acceleration_unit,
            reference_rotation=reference_rotation,
            reference=reference,
            options=CameraImuRunOptions(
                frame_stride=args.frame_stride,
                max_seconds=args.max_seconds,
                evaluation=evaluation,
            ),
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError, ImportError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_lidar_lidar_ros2(args: argparse.Namespace) -> int:
    from dataclasses import replace

    import numpy

    from calibrex.evaluation.lidar_lidar_map import (
        LidarLidarMapOptions,
        read_transform,
        run_ros2_lidar_lidar_map,
    )

    command = ["calibrex", "lidar-lidar", "ros2", str(args.bag)]
    command += ["--reference-topic", args.reference_topic, "--target-topic", args.target_topic]
    if args.point_time_field:
        command += ["--point-time-field", args.point_time_field]
    if args.registration_backend == "cuda":
        command += ["--registration-backend", "cuda"]
    if args.odometry_backend == "cuda":
        command += ["--odometry-backend", "cuda"]
    options = LidarLidarMapOptions()
    if args.registration_query_workers != 1:
        command += ["--registration-query-workers", str(args.registration_query_workers)]
        options = replace(
            options, solver=replace(options.solver, query_workers=args.registration_query_workers),
        )
    try:
        reference_transform = None
        reference = None
        if args.body_transforms:
            first, second = (read_transform(path) for path in args.body_transforms)
            reference_transform = numpy.linalg.inv(first) @ second
            reference = f"inv({args.body_transforms[0].name}) @ {args.body_transforms[1].name}"
            command += ["--body-transforms", *(str(path) for path in args.body_transforms)]
        if args.initial is not None:
            initial = read_transform(args.initial)
            command += ["--initial", str(args.initial)]
        elif reference_transform is not None:
            initial = reference_transform
        else:
            raise ValueError("give --initial or --body-transforms for the initial value")
        if args.max_seconds is not None:
            command += ["--max-seconds", str(args.max_seconds)]
        artifact = run_ros2_lidar_lidar_map(
            args.bag,
            reference_topic=args.reference_topic,
            target_topic=args.target_topic,
            initial=initial,
            point_time_field=args.point_time_field,
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            reference_transform=reference_transform,
            reference=reference,
            max_seconds=args.max_seconds,
            command=command,
            backend=args.registration_backend,
            odometry_backend=args.odometry_backend,
            options=options,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_lidar_vehicle_kitti(args: argparse.Namespace) -> int:
    from calibrex.evaluation.vehicle_frame import run_kitti_lidar_vehicle

    command = ["calibrex", "lidar-vehicle", "kitti", *(path.name for path in args.drives)]
    command += ["--output", str(args.output)]
    try:
        artifact = run_kitti_lidar_vehicle(args.drives, command=command)
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "references": [
                {"name": item.name, "difference_deg": item.difference_deg}
                for item in artifact.references
            ],
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_imu_vehicle_kitti(args: argparse.Namespace) -> int:
    from scipy.spatial.transform import Rotation as _Rotation

    from calibrex.core.vehicle_frame_rotation import load_vehicle_frame_rotation
    from calibrex.evaluation.vehicle_frame import run_kitti_imu_vehicle

    command = ["calibrex", "imu-vehicle", "kitti", *(path.name for path in args.drives)]
    try:
        lidar_rotation = None
        if args.lidar_vehicle is not None:
            lidar = load_vehicle_frame_rotation(args.lidar_vehicle)
            if lidar.rotation_quat_xyzw is None:
                raise ValueError(f"{args.lidar_vehicle} has no rotation")
            lidar_rotation = _Rotation.from_quat(lidar.rotation_quat_xyzw).as_matrix()
            command += ["--lidar-vehicle", str(args.lidar_vehicle)]
        command += ["--output", str(args.output)]
        artifact = run_kitti_imu_vehicle(
            args.drives, lidar_vehicle_rotation=lidar_rotation, command=command
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "references": [
                {"name": item.name, "difference_deg": item.difference_deg}
                for item in artifact.references
            ],
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_gnss_imu_compose(args: argparse.Namespace) -> int:
    from calibrex.evaluation.gnss_imu_lever_arm import compose_gnss_imu_lever_arm

    command = ["calibrex", "gnss-imu", "compose", "--gnss-lidar", args.gnss_lidar.name]
    command += ["--imu-lidar-rotation", args.imu_lidar_rotation.name]
    command += ["--imu-lidar-translation", args.imu_lidar_translation.name]
    if args.reference:
        command += ["--reference", *(str(value) for value in args.reference)]
    try:
        artifact = compose_gnss_imu_lever_arm(
            args.gnss_lidar,
            args.imu_lidar_rotation,
            args.imu_lidar_translation,
            reference_m=args.reference,
            reference=args.reference_name,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "lever_arm_m": artifact.lever_arm_m,
            "calibrated_dofs": artifact.calibrated_dofs,
        },
        args.json,
    )
    return 0


def _emit_lidar_wheel(artifact: Any, output: Path, as_json: bool) -> int:
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(output),
            "calibrated_parameters": artifact.calibrated_parameters,
            "speed_scale": artifact.speed_scale,
            "time_offset_s": artifact.time_offset_s,
            "reasons": artifact.policy_reasons,
        },
        as_json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_lidar_wheel_trajectory(args: argparse.Namespace) -> int:
    from calibrex.evaluation.lidar_wheel import run_trajectory_lidar_wheel

    command = ["calibrex", "lidar-wheel", "trajectory", "--trajectory", args.trajectory.name]
    command += ["--wheel", args.wheel.name, "--output", str(args.output)]
    try:
        artifact = run_trajectory_lidar_wheel(
            args.trajectory.read_text(encoding="utf-8"),
            args.wheel.read_text(encoding="utf-8"),
            sequence_id=args.trajectory.stem,
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    return _emit_lidar_wheel(artifact, args.output, args.json)


def _cmd_lidar_wheel_kitti(args: argparse.Namespace) -> int:
    from scipy.spatial.transform import Rotation as _Rotation

    from calibrex.core.vehicle_frame_rotation import load_vehicle_frame_rotation
    from calibrex.evaluation.lidar_wheel import run_kitti_lidar_wheel

    command = ["calibrex", "lidar-wheel", "kitti", *(path.name for path in args.drives)]
    try:
        rotation = None
        if args.lidar_vehicle is not None:
            lidar = load_vehicle_frame_rotation(args.lidar_vehicle)
            if lidar.rotation_quat_xyzw is not None:
                rotation = _Rotation.from_quat(lidar.rotation_quat_xyzw).as_matrix()
            command += ["--lidar-vehicle", str(args.lidar_vehicle)]
        command += ["--output", str(args.output)]
        artifact = run_kitti_lidar_wheel(
            args.drives, lidar_vehicle_rotation=rotation, command=command
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    return _emit_lidar_wheel(artifact, args.output, args.json)


def _cmd_camera_imu_focal(args: argparse.Namespace) -> int:
    from calibrex.core.io import read_mapping
    from calibrex.evaluation.camera_focal import run_ros2_camera_focal_check

    try:
        chain = read_mapping(args.camchain)
        entry = chain.get(args.camera)
        if not isinstance(entry, dict):
            raise ValueError(f"{args.camchain} has no camera {args.camera!r}")
        image_topic = args.image_topic or entry.get("rostopic")
        if not image_topic:
            raise ValueError("no --image-topic given and the camchain has no rostopic")
        command = ["calibrex", "camera-imu", "focal", args.bag.name, "--camchain"]
        command += [args.camchain.name, "--camera", args.camera, "--imu-topic", args.imu_topic]
        command += ["--rotation", args.rotation.name, "--output", str(args.output)]
        artifact = run_ros2_camera_focal_check(
            str(args.bag),
            image_topic=str(image_topic),
            imu_topic=args.imu_topic,
            camera_entry=entry,
            rotation_artifact_path=str(args.rotation),
            dataset_family=args.dataset_family,
            dataset_license=args.dataset_license,
            frame_stride=args.frame_stride,
            command=command,
        )
        artifact.save(args.output)
    except (OSError, ValueError, ImportError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "fx_estimate_px": artifact.fx_estimate_px,
            "fy_estimate_px": artifact.fy_estimate_px,
            "rate_ratio": artifact.rate_ratio,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_ins_lidar_kitti(args: argparse.Namespace) -> int:
    from calibrex.evaluation.ins_lidar_hand_eye import (
        InsLidarRunOptions,
        run_kitti_ins_lidar_hand_eye,
    )
    from calibrex.solvers.trajectory_hand_eye_solver import DofPrior, TrajectoryHandEyeOptions

    command = ["calibrex", "ins-lidar", "kitti", *(str(path) for path in args.drives)]
    command += ["--output", str(args.output), "--block-duration", str(args.block_duration)]
    if args.max_frames is not None:
        command += ["--max-frames", str(args.max_frames)]
    priors = []
    for text in args.prior:
        command += ["--prior", text]
        try:
            dof, _, rest = text.partition("=")
            value, _, sigma = rest.partition(":")
            priors.append(DofPrior(dof=dof, value=float(value), sigma=float(sigma), source="cli"))
        except ValueError as exc:
            _die(f"invalid --prior {text!r}: {exc}")
    options = InsLidarRunOptions(
        block_duration_s=args.block_duration,
        solver=TrajectoryHandEyeOptions(priors=tuple(priors)),
    )
    try:
        artifact = run_kitti_ins_lidar_hand_eye(
            args.drives, options, max_frames=args.max_frames, command=command
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.policy_status,
            "artifact": str(args.output),
            "calibrated_dofs": artifact.calibrated_dofs,
            "reasons": artifact.policy_reasons,
        },
        args.json,
    )
    return 1 if artifact.policy_status == "fail" else 0


def _cmd_sota_audit(args: argparse.Namespace) -> int:
    from calibrex.evaluation.sota_audit import audit_sota_claim

    command = ["calibrex", "sota", "audit", str(args.protocol), "--output", str(args.output)]
    try:
        audit = audit_sota_claim(args.protocol, audit_id=args.audit_id, command=command)
        audit.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "audit": str(args.output),
            "pair_id": audit.scope.pair_id,
            "verdict": audit.verdict,
            "achieved_dataset_families": audit.achieved_dataset_families,
            "achieved_independent_rig_count": audit.achieved_independent_rig_count,
            "requirement_status": {item.requirement_id: item.status for item in audit.requirements},
        },
        args.json,
    )
    return 0 if audit.verdict == "supported" else 2


def _cmd_sota_leaderboard(args: argparse.Namespace) -> int:
    from calibrex.evaluation.sota_leaderboard import (
        build_sota_leaderboard,
        render_sota_leaderboard_markdown,
    )

    command = ["calibrex", "sota", "leaderboard", *(str(path) for path in args.audits)]
    command += ["--output", str(args.output)]
    for pair in args.target_pair:
        command += ["--target-pair", pair]
    try:
        leaderboard = build_sota_leaderboard(
            args.audits,
            target_pairs=args.target_pair,
            command=command,
        )
        leaderboard.save(args.output)
        if args.markdown is not None:
            args.markdown.parent.mkdir(parents=True, exist_ok=True)
            args.markdown.write_text(
                render_sota_leaderboard_markdown(leaderboard), encoding="utf-8", newline="\n"
            )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "leaderboard": str(args.output),
            "pairs": {item.pair_id: item.standing for item in leaderboard.pairs},
        },
        args.json,
    )
    return 0


def _cmd_camera_lidar_audit_sota(args: argparse.Namespace) -> int:
    from calibrex.evaluation.camera_lidar_sota_audit import audit_camera_lidar_sota_claim

    command = [
        "calibrex",
        "camera-lidar",
        "audit-sota",
        str(args.protocol),
        "--output",
        str(args.output),
    ]
    try:
        audit = audit_camera_lidar_sota_claim(
            args.protocol,
            audit_id=args.audit_id,
            command=command,
        )
        audit.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "audit": str(args.output),
            "verdict": audit.verdict,
            "achieved_dataset_families": (audit.achieved_dataset_families),
            "achieved_independent_rig_count": (audit.achieved_independent_rig_count),
            "requirement_status": {item.requirement_id: item.status for item in audit.requirements},
        },
        args.json,
    )
    return 0 if audit.verdict == "supported" else 2


def _cmd_camera_lidar_empirical_uncertainty(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.empirical_se3_uncertainty import run_empirical_se3_uncertainty

    command = [
        "calibrex",
        "camera-lidar",
        "empirical-uncertainty",
        str(args.correspondence),
        str(args.initial_problem),
        "--result-dir",
        str(args.result_dir),
        "--output",
        str(args.output),
    ]
    if args.workers != 1:
        command.extend(["--workers", str(args.workers)])
    try:
        artifact = run_empirical_se3_uncertainty(
            args.correspondence,
            args.initial_problem,
            result_directory=args.result_dir,
            command=" ".join(command),
            block_length=args.block_length,
            target_coverage=args.target_coverage,
            resample_count=args.resample_count,
            workers=args.workers,
            seed=args.seed,
            fit_block_ratio=args.fit_block_ratio,
            overconfidence_scale=args.overconfidence_scale,
            assess_coverage=not args.stability_only,
            result_id=args.uncertainty_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError, RuntimeError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "uncertainty": str(args.output),
            "policy_status": artifact.policy_status,
            "coverage_score": artifact.coverage_score,
            "observed_coverage_translation": (artifact.observed_coverage_translation),
            "observed_coverage_rotation": artifact.observed_coverage_rotation,
            "observed_coverage_joint": artifact.observed_coverage_joint,
            "interval_halfwidth_translation_m": (artifact.interval_halfwidth_translation_m),
            "interval_halfwidth_rotation_deg": (artifact.interval_halfwidth_rotation_deg),
            "resample_files": len(artifact.iterations),
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_build_contract(args: argparse.Namespace) -> int:
    from calibrex.core.continuous_time_contract import (
        ContinuousTimeClockSemantics,
        ContinuousTimeKnotDomain,
        ContinuousTimeKnotPose,
        ContinuousTimeTrajectoryContract,
        ContinuousTimeTrajectoryProvenance,
    )
    from calibrex.core.io import read_mapping
    from calibrex.core.provenance import git_commit, sha256_path
    from calibrex.core.result import TransformResult

    mapping = read_mapping(args.knots_yaml)
    raw_knots = mapping["knots"]
    if not isinstance(raw_knots, list) or len(raw_knots) < 2:
        raise CalibrexError("knots YAML must contain a non-empty list of knots")
    digest = sha256_path(args.knots_yaml)
    if digest is None:
        raise CalibrexError(f"knots YAML is not readable: {args.knots_yaml}")
    knots = []
    for item in raw_knots:
        timestamp = float(item["timestamp_sec"])
        translation = [float(v) for v in item["translation_m"]]
        quaternion = [float(v) for v in item["rotation_quat_xyzw"]]
        knots.append(
            ContinuousTimeKnotPose(
                timestamp_sec=timestamp,
                transform_world_body=TransformResult(
                    parent=args.world_frame,
                    child=args.body_frame,
                    translation_m=translation,
                    rotation_quat_xyzw=quaternion,
                ),
            )
        )
    contract = ContinuousTimeTrajectoryContract(
        trajectory_id=args.trajectory_id,
        world_frame=args.world_frame,
        body_frame=args.body_frame,
        interpolation=args.interpolation,
        knot_domain=ContinuousTimeKnotDomain(
            minimum_time_sec=knots[0].timestamp_sec,
            maximum_time_sec=knots[-1].timestamp_sec,
            span_sec=knots[-1].timestamp_sec - knots[0].timestamp_sec,
        ),
        clock=ContinuousTimeClockSemantics(),
        knots=knots,
        provenance=ContinuousTimeTrajectoryProvenance(
            generator=__name__,
            generator_version="0.1",
            git_commit=git_commit(),
            source_sha256=digest,
        ),
    )
    contract.save(args.output)
    _emit(
        {
            "status": "ok",
            "trajectory": str(args.output),
            "trajectory_id": contract.trajectory_id,
            "knot_count": contract.knot_count,
            "domain_sec": [
                contract.knot_domain.minimum_time_sec,
                contract.knot_domain.maximum_time_sec,
            ],
        },
        args.json,
    )
    return 0


def _cmd_trajectory_fit(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_trajectory_fit import (
        run_continuous_time_trajectory_fit,
    )

    command = [
        "calibrex",
        "trajectory",
        "fit",
        str(args.trajectory),
        str(args.measurements),
        "--output",
        str(args.output),
    ]
    from calibrex.core.continuous_time_sparse import (
        ContinuousTimeTrajectoryFitOptions,
    )

    try:
        artifact = run_continuous_time_trajectory_fit(
            args.trajectory,
            args.measurements,
            result_id=args.fit_id,
            command=command,
            options=ContinuousTimeTrajectoryFitOptions(
                max_iterations=args.max_iterations,
                initial_damping=args.initial_damping,
            ),
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "fit": str(args.output),
            "fit_id": artifact.fit_id,
            "fit_status": artifact.status,
            "iterations": artifact.iterations,
            "final_objective": artifact.final_objective,
            "final_point_rmse": artifact.final_point_rmse,
            "final_point_to_plane_rmse": artifact.final_point_to_plane_rmse,
            "final_pose_rmse": artifact.final_pose_rmse,
            "final_imu_rotation_rmse_rad": artifact.final_imu_rotation_rmse_rad,
            "final_lever_arm_rmse_m_s2": artifact.final_lever_arm_rmse_m_s2,
            "gyro_bias_rad_s": artifact.gyro_bias_rad_s,
            "lever_arm_body_m": artifact.lever_arm_body_m,
            "imu_clock_offset_sec": artifact.imu_clock_offset_sec,
            "accel_bias_body_m_s2": artifact.accel_bias_body_m_s2,
            "gravity_world_m_s2": artifact.gravity_world_m_s2,
        },
        args.json,
    )
    return 0


def _cmd_trajectory_recover_point_to_plane(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_lidar_point_to_plane import (
        run_synthetic_lidar_point_to_plane_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-point-to-plane",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_lidar_point_to_plane_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "fit_status": artifact.fit_status,
            "max_knot_error": artifact.max_knot_error,
            "holdout_point_to_plane_rmse_m": artifact.holdout_point_to_plane_rmse_m,
            "known_bad_rmse_delta_m": artifact.known_bad_rmse_delta_m,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_recover_imu_preintegration(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_imu_preintegration import (
        run_synthetic_imu_preintegration_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-imu-preintegration",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_imu_preintegration_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "fit_status": artifact.fit_status,
            "max_knot_rotation_error_rad": artifact.max_knot_rotation_error_rad,
            "gyro_bias_error_rad_s": artifact.gyro_bias_error_rad_s,
            "holdout_imu_rotation_rmse_rad": artifact.holdout_imu_rotation_rmse_rad,
            "known_bad_rmse_delta_rad": artifact.known_bad_rmse_delta_rad,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_recover_imu_lever_arm(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_imu_lever_arm import (
        run_synthetic_imu_lever_arm_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-imu-lever-arm",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_imu_lever_arm_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "fit_status": artifact.fit_status,
            "max_knot_translation_error_m": artifact.max_knot_translation_error_m,
            "lever_arm_error_m": artifact.lever_arm_error_m,
            "holdout_lever_arm_rmse_m_s2": artifact.holdout_lever_arm_rmse_m_s2,
            "known_bad_rmse_delta_m_s2": artifact.known_bad_rmse_delta_m_s2,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_recover_imu_clock_offset(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_imu_clock_offset import (
        run_synthetic_imu_clock_offset_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-imu-clock-offset",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_imu_clock_offset_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "fit_status": artifact.fit_status,
            "max_knot_rotation_error_rad": artifact.max_knot_rotation_error_rad,
            "imu_clock_offset_error_sec": artifact.imu_clock_offset_error_sec,
            "holdout_imu_rotation_rmse_rad": artifact.holdout_imu_rotation_rmse_rad,
            "known_bad_rmse_delta_rad": artifact.known_bad_rmse_delta_rad,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_recover_imu_accel_bias(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_imu_accel_bias import (
        run_synthetic_imu_accel_bias_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-imu-accel-bias",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_imu_accel_bias_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "fit_status": artifact.fit_status,
            "max_knot_translation_error_m": artifact.max_knot_translation_error_m,
            "accel_bias_error_m_s2": artifact.accel_bias_error_m_s2,
            "gravity_error_m_s2": artifact.gravity_error_m_s2,
            "holdout_lever_arm_rmse_m_s2": artifact.holdout_lever_arm_rmse_m_s2,
            "known_bad_rmse_delta_m_s2": artifact.known_bad_rmse_delta_m_s2,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_recover_lidar_imu_joint(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_lidar_imu_joint import (
        run_synthetic_lidar_imu_joint_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-lidar-imu-joint",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
        "--trajectory",
        args.trajectory,
    ]
    try:
        artifact = run_synthetic_lidar_imu_joint_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
            trajectory=args.trajectory,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "policy_reason": artifact.policy_reason,
            "interpolation": artifact.interpolation,
            "fit_status": artifact.fit_status,
            "parameter_errors": {
                record.name: record.error_norm for record in artifact.parameters
            },
            "controls_detected": sum(record.detected for record in artifact.controls),
            "controls": len(artifact.controls),
            "entangled_blocks": [
                f"{record.block_a}/{record.block_b}"
                for record in artifact.separability
                if record.entangled
            ],
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_trajectory_recover_imu_intrinsics(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_imu_intrinsics import (
        run_synthetic_imu_intrinsics_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-imu-intrinsics",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_imu_intrinsics_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "fit_status": artifact.fit_status,
            "gyro_scale_error": artifact.gyro_scale_error,
            "accel_scale_error": artifact.accel_scale_error,
            "holdout_imu_rotation_rmse_rad": artifact.holdout_imu_rotation_rmse_rad,
            "holdout_lever_arm_rmse_m_s2": artifact.holdout_lever_arm_rmse_m_s2,
            "known_bad_imu_rmse_delta_rad": artifact.known_bad_imu_rmse_delta_rad,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_lifecycle_simulate(args: argparse.Namespace) -> int:
    from calibrex.evaluation.calibration_lifecycle import (
        run_synthetic_calibration_lifecycle,
    )

    command = [
        "calibrex",
        "lifecycle",
        "simulate",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_calibration_lifecycle(
            seed=args.seed,
            command=command,
            lifecycle_id=args.lifecycle_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "lifecycle": str(args.output),
            "policy_status": artifact.policy_status,
            "adoption_count": artifact.adoption_count,
            "rejection_count": artifact.rejection_count,
            "rollback_count": artifact.rollback_count,
            "weak_observability_installed_delta_m": (artifact.weak_observability_installed_delta_m),
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_lifecycle_init(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import init_registry

    try:
        registry = init_registry(
            args.registry_root,
            registry_id=args.registry_id,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "init"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "registry_root": str(registry.root),
            "registry_id": registry.manifest().registry_id,
            "schema_version": registry.manifest().schema_version,
        },
        args.json,
    )
    return 0


def _cmd_lifecycle_register_sensor(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import register_sensor

    try:
        event = register_sensor(
            args.registry_root,
            sensor_id=args.sensor_id,
            vehicle_id=args.vehicle_id,
            sensor_kit_id=args.sensor_kit_id,
            serial=args.serial,
            model=args.model,
            firmware=args.firmware,
            mount=args.mount,
            frame=args.frame,
            install=args.install,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "register-sensor"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(_lifecycle_event_summary(event), args.json)
    return 0


def _cmd_lifecycle_capture(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import record_capture

    try:
        event = record_capture(
            args.registry_root,
            capture_manifest=args.capture_manifest,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "capture"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(_lifecycle_event_summary(event), args.json)
    return 0 if event.status == "CAPTURED" else 2


def _cmd_lifecycle_register_edge(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import register_calibration_edge

    try:
        event = register_calibration_edge(
            args.registry_root,
            edge_id=args.edge_id,
            vehicle_id=args.vehicle_id,
            sensor_kit_id=args.sensor_kit_id,
            parent_frame=args.parent_frame,
            child_frame=args.child_frame,
            incumbent_transform=args.incumbent_transform,
            incumbent_result=args.incumbent_result,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "register-edge"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(_lifecycle_event_summary(event), args.json)
    return 0


def _cmd_lifecycle_evaluate(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import evaluate_lifecycle

    try:
        artifact = evaluate_lifecycle(
            args.registry_root,
            edge_ids=args.edge_id,
            capture_manifest=args.capture_manifest,
            candidate_result=args.candidate_result,
            candidate_transform=args.candidate_transform,
            candidate_pilot=args.candidate_pilot,
            evidence=args.evidence,
            assessment=args.assessment,
            promotion=args.promotion,
            smoke=args.smoke,
            policy=args.policy,
            output=args.output,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "evaluate"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": artifact.status,
            "admission": artifact.admission,
            "evaluation_id": artifact.evaluation_id,
            "evaluation": str(args.output) if args.output else None,
            "reason": artifact.reason,
            "schema_version": artifact.schema_version,
        },
        args.json,
    )
    return 0 if artifact.status == "PASS" and artifact.admission == "ADOPT" else 2


def _cmd_lifecycle_promote(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import promote_lifecycle

    try:
        event = promote_lifecycle(
            args.registry_root,
            edge_ids=args.edge_id,
            evaluation=args.evaluation,
            promotion=args.promotion,
            smoke=args.smoke,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "promote"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(_lifecycle_event_summary(event), args.json)
    return 0


def _cmd_lifecycle_rollback(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import rollback_lifecycle

    try:
        event = rollback_lifecycle(
            args.registry_root,
            edge_id=args.edge_id,
            target_sequence=args.target_sequence,
            target_event_sha256=args.target_event_sha256,
            promotion=args.promotion,
            operator=args.operator,
            reason=args.reason,
            timestamp=args.timestamp,
            command=["calibrex", "lifecycle", "rollback"],
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(_lifecycle_event_summary(event), args.json)
    return 0


def _cmd_lifecycle_record_ci(args: argparse.Namespace) -> int:
    from calibrex.calibration_ci_lifecycle import record_calibration_ci

    command = ["calibrex", "lifecycle", "record-ci", str(args.ci_decision)]
    command += ["--registry-root", str(args.registry_root), "--edge-id", args.edge_id]
    command += ["--capture-manifest", str(args.capture_manifest)]
    for flag, value in (("--promotion", args.promotion), ("--smoke", args.smoke)):
        if value is not None:
            command += [flag, str(value)]
    if args.promote:
        command.append("--promote")
    if args.rollback_on_fail:
        command.append("--rollback-on-fail")
    try:
        record = record_calibration_ci(
            args.ci_decision,
            args.registry_root,
            edge_id=args.edge_id,
            capture_manifest=args.capture_manifest,
            promotion=args.promotion,
            smoke=args.smoke,
            promote=args.promote,
            rollback_on_fail=args.rollback_on_fail,
            operator=args.operator,
            timestamp=args.timestamp,
            command=command,
        )
        if args.output is not None:
            record.save(args.output)
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(record.model_dump(mode="json", exclude_none=True), args.json)
    return 0 if record.registry_valid else 1


def _cmd_lifecycle_verify(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import verify_registry

    try:
        report = verify_registry(
            args.registry_root,
            verify_sources=not args.no_verify_sources,
        )
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(report.model_dump(mode="json"), args.json)
    return 0 if report.valid else 1


def _cmd_lifecycle_status(args: argparse.Namespace) -> int:
    from calibrex.core.lifecycle_registry import load_registry

    try:
        status = load_registry(args.registry_root).status()
    except (OSError, ValueError, CalibrexError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(status.model_dump(mode="json"), args.json)
    return 0


def _lifecycle_event_summary(event: Any) -> dict[str, Any]:
    return {
        "status": "ok",
        "event_type": event.event_type,
        "event_status": event.status,
        "admission": event.admission,
        "sequence": event.sequence,
        "event_sha256": event.event_sha256,
        "previous_event_sha256": event.previous_event_sha256,
        "registry_id": event.registry_id,
        "edge_ids": event.edge_ids,
    }


def _cmd_trajectory_recover_sliding_window(args: argparse.Namespace) -> int:
    from calibrex.evaluation.continuous_time_sliding_window import (
        run_synthetic_sliding_window_recovery,
    )

    command = [
        "calibrex",
        "trajectory",
        "recover-sliding-window",
        "--output",
        str(args.output),
        "--seed",
        str(args.seed),
    ]
    try:
        artifact = run_synthetic_sliding_window_recovery(
            seed=args.seed,
            command=command,
            recovery_id=args.recovery_id,
        )
        artifact.save(args.output)
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "ok",
            "recovery": str(args.output),
            "policy_status": artifact.policy_status,
            "batch_fit_status": artifact.batch_fit_status,
            "sliding_fit_status": artifact.sliding_fit_status,
            "max_overlap_translation_error_m": artifact.max_overlap_translation_error_m,
            "sliding_holdout_rmse_m": artifact.sliding_holdout_rmse_m,
            "known_bad_rmse_delta_m": artifact.known_bad_rmse_delta_m,
        },
        args.json,
    )
    return 0 if artifact.policy_status != "fail" else 2


def _cmd_camera_lidar_audit_external_baselines(
    args: argparse.Namespace,
) -> int:
    from calibrex.evaluation.camera_lidar_external_baseline_audit import (
        materialize_camera_lidar_external_baseline_audit,
    )

    command = [
        "calibrex",
        "camera-lidar",
        "audit-external-baselines",
        str(args.problem),
        str(args.protocol),
        "--output-dir",
        str(args.output_dir),
        "--koide-source-commit",
        args.koide_source_commit,
        "--unicalib-source-commit",
        args.unicalib_source_commit,
    ]
    try:
        artifacts = materialize_camera_lidar_external_baseline_audit(
            args.problem,
            args.protocol,
            output_directory=args.output_dir,
            koide_source_commit=args.koide_source_commit,
            unicalib_source_commit=args.unicalib_source_commit,
            command=command,
        )
    except (OSError, ValueError) as exc:
        raise CalibrexError(str(exc)) from exc
    _emit(
        {
            "status": "incomplete",
            "comparable_external_baseline_count": 0,
            "koide_status": artifacts.koide.status,
            "koide_audit": str(artifacts.koide_path),
            "unicalib_status": artifacts.unicalib.status,
            "unicalib_audit": str(artifacts.unicalib_path),
            "release_gate": "blocked",
        },
        args.json,
    )
    return 2


def _cmd_visualize(args: argparse.Namespace) -> int:
    from calibrex.core.result import load_result
    from calibrex.visualization.overlays import write_camera_lidar_overlay_artifact
    from calibrex.visualization.report import write_report_artifacts
    from calibrex.visualization.rig3d import write_rig_3d_artifact

    result = load_result(args.result)
    if args.reference_result:
        _merge_reference_result(result, load_result(args.reference_result))
    output_dir = args.output_dir or args.result.parent
    html_path = output_dir / "report.html"
    if args.export_html:
        output_dir.mkdir(parents=True, exist_ok=True)
        write_camera_lidar_overlay_artifact(result, output_dir / "artifacts")
        write_rig_3d_artifact(result, output_dir / "artifacts")
        report_artifacts = write_report_artifacts(result, output_dir)
    else:
        report_artifacts = {}
    payload = {
        "status": "ok",
        "html_report": str(html_path) if args.export_html else result.artifacts.html_report,
        "rig_3d_viewer": result.artifacts.rig_3d_viewer,
        "camera_lidar_overlay": result.artifacts.camera_lidar_overlay,
        "report_artifacts": report_artifacts,
    }
    _emit(payload, args.json)
    return 0


def _cmd_capture_inspect(args: argparse.Namespace) -> int:
    from calibrex.core.capture_manifest import inspect_capture

    sensors: list[SensorIdentity] = []
    for specification in args.sensor:
        try:
            sensors.append(_parse_capture_sensor(specification))
        except ValueError as exc:
            _die(str(exc))
    command = ["calibrex", "capture", "inspect", str(args.path)]
    if args.type != "auto":
        command.extend(["--type", str(args.type)])
    for option, value in (
        ("--capture-id", args.capture_id),
        ("--session-id", args.session_id),
        ("--vehicle-id", args.vehicle_id),
        ("--sensor-kit-id", args.sensor_kit_id),
    ):
        if value is not None:
            command.extend([option, str(value)])
    for specification in args.sensor:
        command.extend(["--sensor", specification])
    if args.readiness_profile != "strict":
        command.extend(["--readiness-profile", str(args.readiness_profile)])
    for stream_id in args.required_stream:
        command.extend(["--required-stream", stream_id])
    for stream_id in args.optional_stream:
        command.extend(["--optional-stream", stream_id])
    for stream_kind in args.required_kind:
        command.extend(["--required-kind", stream_kind])
    if args.config is not None:
        command.extend(["--config", str(args.config)])
    if args.sample_limit != 4:
        command.extend(["--sample-limit", str(args.sample_limit)])
    if args.output is not None:
        command.extend(["--output", str(args.output)])
    if args.json:
        command.append("--json")
    manifest = inspect_capture(
        args.path,
        source_format=str(args.type),
        capture_id=args.capture_id,
        session_id=args.session_id,
        vehicle_id=args.vehicle_id,
        sensor_kit_id=args.sensor_kit_id,
        sensors=sensors,
        config_path=args.config,
        command=command,
        readiness_profile=cast(Literal["strict", "declared"], args.readiness_profile),
        required_streams=tuple(args.required_stream),
        optional_streams=tuple(args.optional_stream),
        required_stream_kinds=tuple(args.required_kind),
        sample_limit=args.sample_limit,
    )
    if args.output is not None:
        manifest.save(args.output)
    payload = manifest.model_dump(mode="json", exclude_none=False)
    if args.json:
        _emit(payload, as_json=True)
    else:
        print(f"Capture manifest: {manifest.status.upper()}")
        print(f"  source: {args.path}")
        print(f"  streams: {len(manifest.streams)}")
        print(f"  sensors: {len(manifest.sensors)}")
        if manifest.source is not None and manifest.source.mcap_integrity is not None:
            print(f"  mcap_integrity: {manifest.source.mcap_integrity.status}")
        print(f"  summary: {manifest.summary}")
        for check in manifest.checks:
            print(f"  {check.check_id}: {check.status} - {check.reason}")
        for action in manifest.actions:
            print(f"  next: {action.message}")
        print(f"  artifact_sha256: {manifest.artifact_sha256}")
        if args.output is not None:
            print(f"  artifact: {args.output}")
    return 0


def _cmd_capture_verify(args: argparse.Namespace) -> int:
    """Verify a capture manifest and its declared external inputs."""
    from calibrex.core.capture_manifest import verify_capture_manifest_inputs


    try:
        report = verify_capture_manifest_inputs(args.manifest)
    except (OSError, ValueError) as exc:
        _die(str(exc))
    payload = report.model_dump(mode="json", exclude_none=False)
    if args.json:
        _emit(payload, as_json=True)
    else:
        print(f"Capture manifest verification: {'PASS' if report.valid else 'FAIL'}")
        print(f"  manifest: {args.manifest}")
        print(f"  self_digest: {report.self_digest_status}")
        for item in report.inputs:
            print(f"  {item.role}:{item.identifier}: {item.status} - {item.reason}")
        print(f"  summary: {report.summary}")
    return 0 if report.valid else 1


def _parse_capture_sensor(specification: str) -> SensorIdentity:
    from calibrex.core.capture_manifest import SensorIdentity, SensorType

    fields = specification.split(":")
    if len(fields) < 2 or not fields[0] or not fields[1]:
        raise ValueError("--sensor must be ID:TYPE[:SERIAL[:MODEL[:FIRMWARE[:MOUNT[:FRAME]]]]]")
    if len(fields) > 7:
        raise ValueError("--sensor accepts at most seven colon-separated fields")
    values = fields + [None] * (7 - len(fields))
    try:
        return SensorIdentity(
            sensor_id=values[0] or "",
            type=cast(SensorType, values[1]),
            serial=values[2],
            model=values[3],
            firmware=values[4],
            mount_id=values[5],
            frame_id=values[6],
        )
    except ValueError as exc:
        raise ValueError(f"invalid --sensor {specification!r}: {exc}") from exc


def _cmd_inspect(args: argparse.Namespace) -> int:
    from calibrex.core.config import DatasetConfig, DatasetType
    from calibrex.data.inspect import inspect_dataset

    dataset_type = cast(DatasetType, str(args.type).replace("-", "_"))
    inspection = inspect_dataset(
        DatasetConfig(
            type=dataset_type,
            path=str(args.path),
            sample_limit=args.sample_limit,
        )
    )
    if args.json:
        _emit(inspection.as_dict(), as_json=True)
    else:
        _emit_inspection(inspection)
    return 0


def _promotion_policy_from_args(args: argparse.Namespace) -> AutowarePromotionPolicy:
    from calibrex.export.autoware_promotion import AutowarePromotionPolicy

    return AutowarePromotionPolicy(
        base_frame=args.base_frame,
        sensor_kit_base_frame=args.sensor_kit_base_frame,
        allowed_frames=list(args.allowed_frame),
        allowed_topics=list(args.allowed_topic),
        allowed_files=list(args.allowed_file),
        required_files=list(args.required_file),
        allow_warnings=bool(args.allow_warnings),
        profile=args.profile,
        require_smoke_for_apply=bool(args.require_smoke_for_apply),
    )


def _cmd_autoware_promotion_plan(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_promotion import (
        AutowarePromotionRoots,
        build_autoware_promotion_plan,
    )

    roots = AutowarePromotionRoots(
        workspace_root=args.workspace_root,
        package_root=args.package_root,
        individual_params_root=args.individual_params_root,
        sensor_kit_description_root=args.sensor_kit_description_root,
    )
    artifact = build_autoware_promotion_plan(
        args.candidate,
        roots=roots,
        vehicle_id=args.vehicle_id,
        sensor_kit_id=args.sensor_kit_id,
        baseline_manifest_sha256=args.baseline_manifest_sha256,
        policy=_promotion_policy_from_args(args),
        command=["calibrex", "autoware", "promotion", "plan", str(args.candidate)],
    )
    artifact.save(args.output)
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["plan"] = str(args.output)
    summary = {
        "plan": str(args.output),
        "status": artifact.status,
        "decision": artifact.decision,
        "reason": artifact.reason,
    }
    _emit(payload if args.json else summary, args.json)
    return 0 if artifact.status == "PASS" else 1


def _cmd_autoware_promotion_verify(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_promotion import verify_autoware_promotion

    artifact = verify_autoware_promotion(
        args.plan, command=["calibrex", "autoware", "promotion", "verify", str(args.plan)]
    )
    # Verification is a read-only operation by default.  Persist a refreshed
    # artifact only when the caller explicitly supplies --output.
    destination = args.output
    if destination is not None:
        artifact.save(destination)
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["plan"] = str(destination or args.plan)
    summary = {
        "plan": str(destination or args.plan),
        "status": artifact.status,
        "decision": artifact.decision,
        "reason": artifact.reason,
    }
    _emit(payload if args.json else summary, args.json)
    return 0 if artifact.status == "PASS" else 1


def _cmd_autoware_promotion_apply(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_promotion import apply_autoware_promotion

    artifact = apply_autoware_promotion(
        args.plan,
        smoke_artifact=args.smoke_artifact,
        output_path=args.output,
    )
    destination = args.output or args.plan
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["plan"] = str(destination)
    summary = {
        "plan": str(destination),
        "status": artifact.status,
        "decision": artifact.decision,
        "application": artifact.application.status,
    }
    _emit(payload if args.json else summary, args.json)
    return 0


def _cmd_autoware_promotion_rollback(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_promotion import rollback_autoware_promotion

    artifact = rollback_autoware_promotion(args.plan, output_path=args.output)
    destination = args.output or args.plan
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["plan"] = str(destination)
    summary = {
        "plan": str(destination),
        "status": artifact.status,
        "decision": artifact.decision,
        "application": artifact.application.status,
    }
    _emit(payload if args.json else summary, args.json)
    return 0


def _cmd_autoware_smoke_run(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_smoke import (
        AutowareSmokeCommand,
        AutowareSmokeConfig,
        AutowareSmokePolicy,
        run_autoware_smoke,
    )

    commands: list[AutowareSmokeCommand] = []
    for specification in args.stage_command:
        if "=" not in specification:
            _die("--stage-command must be STAGE=JSON_ARGV")
        stage, raw_argv = specification.split("=", 1)
        try:
            argv = json.loads(raw_argv)
        except json.JSONDecodeError as exc:
            _die(f"invalid --stage-command JSON: {exc}")
        if not isinstance(argv, list) or any(not isinstance(item, str) for item in argv):
            _die("--stage-command JSON must be an array of strings")
        commands.append(AutowareSmokeCommand(stage=stage, argv=argv))
    try:
        artifact = run_autoware_smoke(
            args.plan,
            config=AutowareSmokeConfig(
                mode=args.mode,
                profile=args.profile,
                commands=commands,
                container_digest=args.container_digest,
                environment_digest=args.environment_digest,
                tool_digest=args.tool_digest,
                precomputed_path=args.precomputed,
                policy=AutowareSmokePolicy(
                    profile=args.profile,
                    stage_timeout_seconds=args.timeout,
                ),
                command=["calibrex", "autoware", "smoke", "run", str(args.plan)],
            ),
            output_path=args.output,
        )
    except (CalibrexError, ValueError, OSError) as exc:
        _die(f"Autoware smoke failed: {exc}")
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["artifact"] = str(args.output)
    summary = {
        "artifact": str(args.output),
        "status": artifact.status,
        "admission_label": artifact.admission_label,
        "reason": artifact.reason,
    }
    _emit(payload if args.json else summary, args.json)
    return 0 if artifact.status == "PASS" else 1


def _cmd_autoware_smoke_import(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_promotion import load_autoware_promotion
    from calibrex.export.autoware_smoke import import_autoware_smoke

    try:
        artifact = import_autoware_smoke(
            args.artifact,
            promotion=load_autoware_promotion(args.plan),
            output_path=args.output,
        )
    except (CalibrexError, ValueError, OSError) as exc:
        _die(f"Autoware smoke import failed: {exc}")
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["artifact"] = str(args.output)
    summary = {
        "artifact": str(args.output),
        "status": artifact.status,
        "admission_label": artifact.admission_label,
        "reason": artifact.reason,
    }
    _emit(payload if args.json else summary, args.json)
    return 0 if artifact.status == "PASS" else 1


def _cmd_autoware_smoke_verify(args: argparse.Namespace) -> int:
    from calibrex.export.autoware_promotion import load_autoware_promotion
    from calibrex.export.autoware_smoke import verify_autoware_smoke

    try:
        artifact = verify_autoware_smoke(
            args.artifact,
            promotion=load_autoware_promotion(args.plan),
        )
    except (CalibrexError, ValueError, OSError) as exc:
        _die(f"Autoware smoke verification failed: {exc}")
    payload = artifact.model_dump(mode="json", exclude_none=False)
    payload["artifact"] = str(args.artifact)
    summary = {
        "artifact": str(args.artifact),
        "status": artifact.status,
        "admission_label": artifact.admission_label,
        "reason": artifact.reason,
    }
    _emit(payload if args.json else summary, args.json)
    return 0 if artifact.status == "PASS" else 1


def _cmd_export(args: argparse.Namespace) -> int:
    from calibrex.core.continuous_time_lidar_artifacts import ContinuousTimeLidarPairArtifact
    from calibrex.core.io import read_mapping
    from calibrex.core.result import load_result
    from calibrex.export.autoware import (
        AutowareExportConfig,
        build_autoware_export,
        write_autoware_export,
    )
    from calibrex.export.ros_tf import export_ros_tf_transforms, export_ros_tf_yaml

    if args.format == "autoware":
        try:
            config = AutowareExportConfig(
                base_frame=args.base_frame,
                sensor_frames=list(args.sensor_frames),
                transform_names=list(args.transform_names),
                invert_transforms=list(args.invert_transforms),
            )
        except ValueError as exc:
            _die(f"invalid Autoware export configuration: {exc}")
        static_tf_output = args.static_tf_output or args.output.with_name(
            f"{args.output.stem}.static_tf.launch.py"
        )
        manifest_output = args.manifest_output or args.output.with_name(
            f"{args.output.stem}.manifest.yaml"
        )
        if args.kind == "continuous-time-lidar-pair":
            artifact = ContinuousTimeLidarPairArtifact.model_validate(read_mapping(args.result))
            transforms = {artifact.variable: artifact.refined_transform}
            export_artifact = build_autoware_export(
                transforms,
                config=config,
                source_path=args.result,
                source_run=artifact.variable,
                quality_grade=artifact.refined_transform.quality.grade,
                command=["calibrex", "export", str(args.result), "--format", "autoware"],
            )
        else:
            result = load_result(args.result)
            export_artifact = build_autoware_export(
                result,
                config=config,
                source_path=args.result,
                command=["calibrex", "export", str(args.result), "--format", "autoware"],
            )
        paths = write_autoware_export(
            export_artifact,
            args.output,
            static_tf_output=static_tf_output,
            manifest_output=manifest_output,
            overwrite=args.force,
        )
        summary = {
            "status": "ok",
            "calibration": str(paths["calibration"]),
            "static_tf": str(paths["static_tf"]),
            "manifest": str(paths["manifest"]),
            "artifact_sha256": export_artifact.artifact_sha256,
            "source_result_sha256": export_artifact.provenance.source_result_sha256,
            "schema_version": export_artifact.schema_version,
        }
        if args.json:
            _emit(summary, as_json=True)
        else:
            print(f"wrote {paths['calibration']}")
            print(f"wrote {paths['static_tf']}")
            print(f"wrote {paths['manifest']}")
        return 0
    if args.kind == "continuous-time-lidar-pair":
        artifact = ContinuousTimeLidarPairArtifact.model_validate(read_mapping(args.result))
        transforms = {artifact.variable: artifact.refined_transform}
        if args.format == "ros-tf":
            export_ros_tf_transforms(transforms, args.output)
        else:
            _die(f"unsupported export format: {args.format}")
    else:
        result = load_result(args.result)
        if args.format == "ros-tf":
            export_ros_tf_yaml(result, args.output)
        else:
            _die(f"unsupported export format: {args.format}")
    print(f"wrote {args.output}")
    return 0


def _merge_reference_result(result: CalibrationResult, reference: CalibrationResult) -> None:
    result.reference_extrinsics.update(reference.reference_extrinsics)
    result.reference_extrinsics.update(reference.transforms)
    result.run.provenance["visualization_reference_run_id"] = reference.run.id


def _starter_config(profile: str) -> dict[str, Any]:
    domain = "autonomous_driving" if profile == "autonomous-driving-rig" else "robotics"
    sensors: dict[str, Any] = {
        "camera0": {
            "type": "camera",
            "model": "pinhole",
            "topic": "/camera/front/image",
            "camera_info_topic": "/camera/front/camera_info",
            "intrinsics": {
                "estimate": False,
                "fx": 720.0,
                "fy": 720.0,
                "cx": 640.0,
                "cy": 360.0,
                "distortion_model": "radtan",
                "distortion": [0.0, 0.0, 0.0, 0.0],
            },
        },
        "lidar0": {
            "type": "lidar",
            "model": "spinning",
            "topic": "/lidar/points",
            "fields": ["x", "y", "z", "intensity"],
        },
        "imu0": {
            "type": "imu",
            "model": "six_axis",
            "topic": "/imu/data",
            "noise": {
                "gyro_noise_density": 0.0002,
                "accel_noise_density": 0.002,
                "gyro_random_walk": 0.00001,
                "accel_random_walk": 0.0001,
            },
        },
    }
    if profile == "autonomous-driving-rig":
        sensors["radar0"] = {
            "type": "radar",
            "model": "automotive_4d",
            "topic": "/radar/front/detections",
        }

    frames: dict[str, Any] = {
        "base": {"root": True},
        "camera0": _child_frame("base", [0.3, 0.0, 0.2]),
        "lidar0": _child_frame("base", [0.0, 0.0, 0.4]),
        "imu0": _child_frame("base", [0.0, 0.0, 0.0]),
    }
    if profile == "autonomous-driving-rig":
        frames["radar0"] = _child_frame("base", [0.8, 0.0, 0.35])

    return {
        "schema_version": "slac.config/v0.1",
        "project": {
            "name": f"{profile}_calibration",
            "description": "Starter Calibrex calibration config",
            "output_dir": "outputs/example",
            "domain": domain,
        },
        "dataset": {
            "type": "filesystem",
            "path": "examples/synthetic_camera_lidar_imu",
            "time_base": "sensor_time_ns",
        },
        "sensors": sensors,
        "frames": frames,
        "time_offsets": {
            "camera0": {"estimate": True, "initial_sec": 0.0, "prior_sigma_sec": 0.01},
            "lidar0": {"estimate": False, "initial_sec": 0.0},
        },
        "pipeline": {
            "type": "multi_sensor_slac",
            "frontends": ["imu_preintegration", "lidar_surfel_map", "camera_features"],
            "factors": {
                "imu_preintegration": {"enabled": True},
                "lidar_point_to_surfel": {"enabled": True},
                "camera_reprojection": {"enabled": True},
            },
        },
        "solver": {
            "backend": "scipy",
            "max_iterations": 50,
            "robust_loss": "huber",
            "convergence_tolerance": 1.0e-6,
        },
        "evaluation": {
            "holdout_ratio": 0.2,
            "kitti": {
                "max_projection_pairs": 3,
                "projection_sample_points": 800,
                "perturbation_rotation_deg": [0.5, 1.0],
                "perturbation_translation_m": [0.05, 0.10],
            },
            "metrics": [
                "reprojection_rmse_px",
                "lidar_point_to_plane_rmse_m",
                "trajectory_consistency",
                "observability_rank",
            ],
        },
        "outputs": {
            "result": "result.yaml",
            "report": "report.html",
            "artifacts_dir": "artifacts",
        },
    }


def _child_frame(parent: str, translation: list[float]) -> dict[str, Any]:
    return {
        "parent": parent,
        "transform": {
            "estimate": True,
            "initial": {
                "translation": translation,
                "rotation_quat_xyzw": [0.0, 0.0, 0.0, 1.0],
            },
            "prior_sigma": {
                "translation_m": 0.2,
                "rotation_deg": 10.0,
            },
        },
    }


def _emit(payload: dict[str, Any], as_json: bool) -> None:
    if as_json:
        print(json.dumps(payload, indent=2, sort_keys=True))
        return
    for key, value in payload.items():
        print(f"{key}: {value}")


def _emit_verification(verification: EvidenceBundleVerification) -> None:
    summary = verification.verification_summary
    if verification.path == verification.source_bundle.path:
        print(f"bundle: {verification.path}")
    else:
        print(f"verification: {verification.path}")
        print(f"source_bundle: {verification.source_bundle.path}")
    print(f"valid: {_format_bool(verification.valid)}")
    print(f"source_bundle_sha256: {verification.source_bundle.sha256}")
    if verification.raw_recomputed_required:
        print("raw_recomputed_required: yes")
    if verification.primary_evidence_materialization is not None:
        materialization = verification.primary_evidence_materialization
        print(
            "primary_evidence: "
            f"metrics_origin={materialization.metrics_origin}, "
            f"data_verified={_format_optional_bool(materialization.data_verified)}"
        )
    print(f"artifacts: {len(verification.checked_artifacts)}/{verification.artifact_count}")
    print(f"input_files: {verification.checked_input_file_count}/{verification.input_file_count}")
    print(
        "claims: "
        f"total={summary.total}, "
        f"ok={summary.ok}, "
        f"failed={summary.failed}, "
        f"skipped={summary.skipped}"
    )
    if summary.by_scope:
        print("claim_scopes:")
        for scope, count in sorted(summary.by_scope.items()):
            print(f"  {scope}: {count}")
    if verification.issues:
        print("issues:")
        for issue in verification.issues:
            print(f"  - {issue}")


def _emit_inspection(inspection: DatasetInspection) -> None:
    print("Dataset")
    print(f"  type: {inspection.dataset_type}")
    print(f"  path: {inspection.path}")
    print(f"  exists: {_format_bool(inspection.exists)}")
    if inspection.manifest:
        print(f"  manifest: {inspection.manifest}")

    print("Streams")
    if not inspection.streams:
        print("  none")
    for stream in inspection.streams:
        count = "unknown" if stream.message_count is None else str(stream.message_count)
        topic = f", topic={stream.topic}" if stream.topic else ""
        sensor = f", sensor={stream.sensor}" if stream.sensor else ""
        print(f"  - {stream.name} ({stream.kind}): {count} messages{topic}{sensor}")

    print("Warnings")
    if not inspection.warnings:
        print("  none")
    for warning in inspection.warnings:
        print(f"  - {warning}")

    _emit_diagnostics(inspection)


def _emit_diagnostics(inspection: DatasetInspection) -> None:
    if not inspection.diagnostics:
        return
    print("Diagnostics")
    for name, diagnostic in sorted(inspection.diagnostics.items()):
        if not isinstance(diagnostic, dict):
            print(f"  {name}: {diagnostic}")
            continue
        print(f"  {name}:")
        for key in _ordered_diagnostic_keys(diagnostic):
            value = diagnostic.get(key)
            if value is not None and value != []:
                print(f"    {key}: {_format_value(value)}")

    lidar_diagnostic_keys = {"velodyne_points", "livox_pcd", "rosbag1"}
    if lidar_diagnostic_keys & set(inspection.diagnostics):
        _emit_lidar_quality_hint(inspection)


def _emit_lidar_quality_hint(inspection: DatasetInspection) -> None:
    from calibrex.evaluation.degeneracy import degeneracy_from_inspection
    from calibrex.evaluation.lidar import lidar_metrics_from_inspection
    from calibrex.evaluation.motion import motion_metrics_from_inspection
    from calibrex.evaluation.recommendations import build_inspection_recommendations
    from calibrex.evaluation.thresholds import apply_metric_thresholds
    from calibrex.evaluation.timing import timing_metrics_from_inspection

    domain = "autonomous_driving" if inspection.dataset_type == "kitti_raw" else "robotics"
    metrics = lidar_metrics_from_inspection(inspection)
    metrics.update(motion_metrics_from_inspection(inspection))
    metrics.update(timing_metrics_from_inspection(inspection))
    apply_metric_thresholds(
        metrics,
        "autonomous_driving" if domain == "autonomous_driving" else "default",
    )
    degeneracy = degeneracy_from_inspection(inspection)
    recommendations = build_inspection_recommendations(metrics, degeneracy, domain=domain)

    print("LiDAR Quality")
    print(f"  degeneracy: {degeneracy.grade.upper()}")
    if degeneracy.reason:
        print(f"  reason: {degeneracy.reason}")
    if metrics:
        print("  metrics:")
        for name, metric in sorted(metrics.items()):
            value = metric.holdout if metric.holdout is not None else metric.value
            if value is None:
                value = metric.train
            suffix = f" {metric.unit}" if metric.unit else ""
            print(f"    - {name}: {metric.grade.upper()} ({_format_value(value)}{suffix})")
    print("  recommendations:")
    for recommendation in recommendations:
        print(f"    - {recommendation}")


def _ordered_diagnostic_keys(diagnostic: dict[str, object]) -> list[str]:
    preferred = [
        "frame_count",
        "status",
        "sampled_frame_count",
        "train_frame_count",
        "holdout_frame_count",
        "sampled_point_count",
        "min_points_per_frame",
        "max_points_per_frame",
        "bounds_min_m",
        "bounds_max_m",
        "intensity_min",
        "intensity_max",
        "intensity_mean",
        "voxel_size_m",
        "planarity_min_points_per_voxel",
        "planarity_voxel_count",
        "local_planarity_mean",
        "roughness_mean_m",
        "map_sharpness_score",
        "point_to_plane_rmse_train_m",
        "point_to_plane_rmse_holdout_m",
        "point_to_plane_median_holdout_m",
        "point_to_plane_p95_holdout_m",
        "train_residual_count",
        "holdout_residual_count",
        "pair_target_transform_applied",
        "pair_transform_convention",
        "pair_voxel_size_m",
        "pair_source_voxel_count",
        "pair_target_voxel_count",
        "pair_shared_voxel_count",
        "pair_unmatched_source_voxel_count",
        "pair_unmatched_target_voxel_count",
        "pair_source_voxel_recall_in_target",
        "pair_target_voxel_recall_in_source",
        "pair_shared_voxel_centroid_rmse_m",
        "packet_count",
        "timestamp_count",
        "duration_sec",
        "mean_speed_mps",
        "max_speed_mps",
        "speed_range_mps",
        "yaw_excitation_deg",
        "pitch_excitation_deg",
        "roll_excitation_deg",
        "mean_acceleration_norm_mps2",
        "camera_lidar_pair_count",
        "camera_lidar_mean_abs_dt_ms",
        "camera_lidar_max_abs_dt_ms",
        "lidar_oxts_pair_count",
        "lidar_oxts_mean_abs_dt_ms",
        "lidar_oxts_max_abs_dt_ms",
        "camera_timestamp_count",
        "lidar_timestamp_count",
        "oxts_timestamp_count",
        "malformed_files",
    ]
    known = [key for key in preferred if key in diagnostic]
    extra = sorted(key for key in diagnostic if key not in set(preferred))
    return known + extra


def _format_bool(value: bool) -> str:
    return "yes" if value else "no"


def _emit_comparison(
    comparison: ResultComparison,
    *,
    enforce_compatible: bool = False,
) -> None:
    summary = comparison.summary
    print(f"left: {comparison.left.run_id} ({comparison.left.grade})")
    print(f"left_materialization: {_format_comparison_materialization(comparison.left)}")
    print(f"right: {comparison.right.run_id} ({comparison.right.grade})")
    print(f"right_materialization: {_format_comparison_materialization(comparison.right)}")
    print(f"metrics: {summary.metric_comparison_count}")
    print(
        "metric_winners: "
        f"left={summary.left_better_metric_count}, "
        f"right={summary.right_better_metric_count}, "
        f"tie={summary.tied_metric_count}, "
        f"not_comparable={summary.not_comparable_metric_count}"
    )
    print(f"transforms: {summary.transform_comparison_count}")
    if summary.max_translation_delta_m is not None:
        print(f"max_translation_delta_m: {summary.max_translation_delta_m:.6g}")
    if summary.max_rotation_delta_deg is not None:
        print(f"max_rotation_delta_deg: {summary.max_rotation_delta_deg:.6g}")
    if comparison.observability.only_right_weak_directions:
        print(f"new_weak_directions: {comparison.observability.only_right_weak_directions}")
    protocol = comparison.protocol_compatibility
    print(f"protocol_compatibility: {protocol.status}")
    print(f"protocol_compatibility_enforced: {_format_bool(enforce_compatible)}")
    if protocol.reasons:
        print(f"protocol_notes: {protocol.reasons}")
    if comparison.evidence_comparisons:
        winners = [item.winner for item in comparison.evidence_comparisons]
        print(f"evidence_checks: {len(comparison.evidence_comparisons)}")
        print(
            "evidence_winners: "
            f"left={winners.count('left')}, "
            f"right={winners.count('right')}, "
            f"tie={winners.count('tie')}, "
            f"not_comparable={winners.count('not_comparable')}"
        )
    not_comparable_reasons = _comparison_not_comparable_reasons(comparison)
    if not_comparable_reasons:
        print("not_comparable_reasons:")
        for reason, count in not_comparable_reasons:
            print(f"  - {reason} ({count})")


def _emit_report_comparison(
    report: ReportComparison,
    *,
    enforce_compatible: bool = False,
) -> None:
    summary = report.summary
    print(f"entries: {summary.entry_count}")
    print(f"comparison_mode: {summary.comparison_mode}")
    if summary.reference_label is not None:
        print(f"reference: {summary.reference_label}")
    for label, entry in report.entries.items():
        provenance = entry.provenance
        role = provenance.dominant_role or "n/a"
        reference_marker = " [reference]" if entry.is_reference else ""
        print(
            f"  {label}{reference_marker}: run_id={entry.side.run_id}, "
            f"grade={entry.side.grade}, "
            f"producer={provenance.dominant_producer}, "
            f"role={role}, "
            f"evidence_level={provenance.dominant_evidence_level}"
        )
    print(f"pairwise_comparisons: {summary.pairwise_comparison_count}")
    print(f"protocol_compatibility: {summary.protocol_compatibility_status}")
    print(f"protocol_compatibility_enforced: {_format_bool(enforce_compatible)}")
    print(
        "pair_compatibility: "
        f"compatible={summary.compatible_pair_count}, "
        f"warning={summary.warning_pair_count}, "
        f"not_comparable={summary.not_comparable_pair_count}"
    )
    if summary.not_comparable_pairs:
        print("not_comparable_pairs:")
        for pair_key in summary.not_comparable_pairs:
            pair = report.pairwise[pair_key]
            reasons = pair.comparison.protocol_compatibility.reasons
            suffix = f": {'; '.join(reasons)}" if reasons else ""
            print(f"  - {pair.left_label} vs {pair.right_label}{suffix}")
    if report.metric_family_rankings:
        print("metric_family_rankings:")
        for family, ranking in report.metric_family_rankings.items():
            print(f"  {family} ({ranking.metric_count} metrics):")
            for entry_rank in ranking.entries:
                rank = "n/a" if entry_rank.rank is None else str(entry_rank.rank)
                print(
                    f"    {rank}. {entry_rank.label}: "
                    f"wins={entry_rank.win_count}, "
                    f"ties={entry_rank.tie_count}, "
                    f"losses={entry_rank.loss_count}, "
                    f"not_comparable={entry_rank.not_comparable_count}"
                )


def _format_comparison_materialization(side: ComparisonSide) -> str:
    parts = [
        f"metrics_origin={side.metrics_origin}",
        f"data_verified={_format_optional_bool(side.data_verified)}",
    ]
    if side.computed_at is not None:
        parts.append(f"computed_at={side.computed_at}")
    return ", ".join(parts)


def _comparison_not_comparable_reasons(
    comparison: ResultComparison,
) -> list[tuple[str, int]]:
    counts: dict[str, int] = {}
    for metric in comparison.metrics.values():
        if metric.winner == "not_comparable" and metric.not_comparable_reason:
            counts[metric.not_comparable_reason] = counts.get(metric.not_comparable_reason, 0) + 1
    for evidence in comparison.evidence_comparisons:
        if evidence.winner == "not_comparable" and evidence.not_comparable_reason:
            counts[evidence.not_comparable_reason] = (
                counts.get(evidence.not_comparable_reason, 0) + 1
            )
    return sorted(counts.items(), key=lambda item: (-item[1], item[0]))


def _format_optional_bool(value: bool | None) -> str:
    if value is None:
        return "n/a"
    return _format_bool(value)


def _format_value(value: object) -> str:
    if value is None:
        return "n/a"
    if isinstance(value, float):
        return f"{value:.6g}"
    if isinstance(value, list | tuple):
        return "[" + ", ".join(_format_value(item) for item in value) + "]"
    return str(value)


def _die(message: str) -> NoReturn:
    raise CalibrexError(message)


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