"""Reproducible, guarded entry points for pallet experiments."""

from __future__ import annotations

import argparse
from collections import Counter
import hashlib
import json
import os
from pathlib import Path
from dataclasses import replace

import torch

from pallet.annotation import (Box, Provenance, Review, SceneAttributes, create_proposals,
                               export_coco, export_yolo,
                               load_jsonl, qa_report, record_review, save_jsonl, seal_splits,
                               is_resolved, reference_eligible, export_audit)
from pallet.data import (apply_normalization, canonical_records, fit_normalization,
                         hash_sensor_files, load_frame, read_pcd,
                         scan_dataset, split_groups, unify_duplicate_groups)
from pallet.data.loader import NormalizationStats
from pallet.experiments.dataset import PalletDataset
from pallet.experiments.dataset import SampleMeta, letterbox_float
from pallet.experiments.evaluate import evaluate, predict_boxes
from pallet.experiments.train import train_yolo
from pallet.models import PalletDetector, RFDETRDetector
from pallet.devices import resolve_device, device_metadata
from pallet.data.protocol import load_protocol


def _sha256(path):
    digest = hashlib.sha256()
    with Path(path).open("rb") as source:
        for chunk in iter(lambda: source.read(4 * 1024 * 1024), b""):
            digest.update(chunk)
    return digest.hexdigest()


def _records(root, *, index_path="outputs/content_hashes.json", protocol_dir=None):
    if protocol_dir:
        records, _, protocol = load_protocol(protocol_dir)
        if str(Path(root).resolve()) != protocol['root']:
            raise ValueError('requested data root differs from frozen protocol')
        return records
    records = canonical_records(scan_dataset(root))
    index = Path(index_path)
    if index.exists():
        records = unify_duplicate_groups(records, json.loads(index.read_text()))
    return records


def _write_json(path, payload):
    destination = Path(path)
    destination.parent.mkdir(parents=True, exist_ok=True)
    temporary = destination.with_name(destination.name + ".tmp")
    temporary.write_text(json.dumps(payload, indent=2, ensure_ascii=False), encoding="utf-8")
    os.replace(temporary, destination)


def _record_run_config(path, config):
    path = Path(path)
    if path.exists():
        previous=json.loads(path.read_text())
        provenance_only={'git_commit','git_dirty'}
        if ({key:value for key,value in previous.items() if key not in provenance_only}
                != {key:value for key,value in config.items() if key not in provenance_only}):
            raise ValueError("run directory has a different label snapshot or configuration; "
                             "use a new output directory")
    else:
        _write_json(path, config)


def _code_fingerprint():
    root=Path(__file__).parent
    paths=[root/'cli.py',root/'devices.py',root/'annotation/workflow.py',root/'annotation/__init__.py',
           root/'human_labeling.py', root/'manual_update.py', root/'mixed_manual_assistant.py',
           *sorted((root/'models').glob('*.py')),*sorted((root/'experiments').glob('*.py')),
           *[root/'data'/name for name in ('__init__.py','loader.py','pcd.py','manifest.py','protocol.py','sensors.py','dedup.py','eligibility.py','orientation.py')]]
    files={str(path.relative_to(root)):_sha256(path) for path in paths}
    return hashlib.sha256(json.dumps(files,sort_keys=True).encode()).hexdigest()


def _assignments(records, seed):
    parts = split_groups(records, seed=seed)
    return {record.group_id: name for name, rows in parts.items() for record in rows}


def cmd_audit(args):
    from pallet.data.manifest import _TIME

    records = scan_dataset(args.root)
    canonical = canonical_records(records)
    root = Path(args.root)
    skipped_pcd = []
    for path in root.rglob("*.pcd"):
        if not path.stat().st_size:
            reason = "zero_byte"
        elif not _TIME.search(path.name):
            reason = "no_capture_timestamp"
        elif not path.name.lower().startswith("point_cloud"):
            reason = "nonstandard_name"
        else:
            continue
        skipped_pcd.append({"path": str(path.relative_to(root)), "reason": reason})
    report = {"raw_sensor_records": len(records), "unique_capture_records": len(canonical),
              "groups": len({row.group_id for row in canonical}),
              "configuration_domains": dict(Counter(row.domain for row in canonical)),
              "modalities": dict(Counter(modality for row in canonical for modality in row.paths)),
              "pcd_excluded_from_timestamp_manifest": sorted(skipped_pcd, key=lambda x: x["path"]),
              "pcd_excluded_count": len(skipped_pcd),
              "dataset_root": str(Path(args.root).resolve()),
              "note": "Configuration domains do not establish physical camera identity."}
    _write_json(args.output, report)
    print(json.dumps(report, ensure_ascii=False))


def cmd_prepare(args):
    records, assignments, protocol = load_protocol(args.protocol)
    from pallet.data.eligibility import eligible_records
    records = eligible_records(records)
    if Path(args.output).exists():
        raise ValueError('annotation output exists; choose a new snapshot path')
    annotations = create_proposals(records, source="unlabeled", actor="prepare")
    for record in records:
        annotations.frames[record.frame_id].domain = record.domain
    seal_splits(annotations, assignments)
    save_jsonl(annotations, args.output)
    _write_json(Path(args.output).with_suffix(".qa.json"), qa_report(annotations))
    print(f"Prepared {len(annotations.frames)} unreviewed captures; annotations: {args.output}")


def cmd_dedup(args):
    records = canonical_records(scan_dataset(args.root))
    index = hash_sensor_files(records, args.output)
    grouped = unify_duplicate_groups(records, index)
    result = {"captures": len(records), "hashed_files": len(index),
              "groups_before": len({row.group_id for row in records}),
              "groups_after": len({row.group_id for row in grouped}),
              "index": str(Path(args.output).resolve())}
    print(json.dumps(result, ensure_ascii=False))


def cmd_review(args):
    annotations = load_jsonl(args.annotations)
    frame = annotations.frames[args.frame_id]
    boxes = [Box(*values) for values in json.loads(args.boxes)] if args.boxes else None
    record_review(frame, Review(args.reviewer, args.decision, note=args.note,
                                blind=not args.assisted), status=args.status, boxes=boxes)
    save_jsonl(annotations, args.annotations)
    print(json.dumps(qa_report(annotations), ensure_ascii=False))


def cmd_import_reviewed(args):
    annotations = load_jsonl(args.annotations)
    pilot = json.loads(Path(args.review_file).read_text())
    if Path(args.output).exists():
        raise ValueError('review output exists; use a new immutable snapshot')
    for item in pilot["frames"]:
        frame = annotations.frames[item["frame_id"]]
        if frame.status != "unreviewed":
            raise ValueError(f"already adjudicated: {frame.frame_id}")
        if item.get('source_anchor_hash') != frame.source_anchor_hash:
            raise ValueError('review import must attest to the exact primary source hash')
        final_boxes = [Box(*values) for values in item['boxes']]
        review_ids = []
        all_same = True
        for review in item["reviews"]:
            note = review["note"] + f" Independent candidate boxes: {review['boxes']}"
            status = review.get('status',item['status'])
            boxes = [Box(*values) for values in review['boxes']]
            all_same = all_same and status==item['status'] and boxes==final_boxes
            record_review(frame, Review(review["reviewer"], 'needs_work', note=note,
                                        blind=review.get('blind',False)),status=status,boxes=boxes,
                          scene=SceneAttributes(domain=frame.domain,tags=tuple(review.get('tags',[]))))
            review_ids.append(frame.reviews[-1].review_id)
        actor = item.get('adjudicator')
        if not actor and not all_same:
            raise ValueError('disagreeing reviews require an identified adjudicator')
        record_review(frame,Review(actor or 'exact-consensus-v1','adjudicate',
                                  adjudicates=tuple(review_ids),blind=item.get('blind_to_detector',False),
                                  note=item.get('adjudication','Exact independent box/status agreement')),
                      status=item['status'],boxes=final_boxes,
                      scene=SceneAttributes(domain=frame.domain,tags=tuple(item.get('tags',[]))))
        if not is_resolved(frame,require_blind=frame.split in {'val','test'}):
            raise ValueError('review import did not establish a resolved reference')
    save_jsonl(annotations, args.output)
    print(json.dumps(qa_report(annotations), ensure_ascii=False))


def cmd_export_labels(args):
    annotations = load_jsonl(args.annotations)
    path = Path(args.output)
    path.mkdir(parents=True, exist_ok=True)
    export_coco(annotations, path / "annotations.coco.json")
    export_yolo(annotations, path / "yolo")
    export_audit(annotations, path / 'audit.json')
    _write_json(path / "quality.json", qa_report(annotations))
    print(f"Exported reviewed label snapshot to {path}")


def cmd_propose(args):
    from pallet.proposals import generate_sam3_proposals
    report = generate_sam3_proposals(args.root, args.annotations, split=args.split,
                                     limit=args.limit, device=args.device)
    _write_json(args.report, report)
    print(json.dumps(report, ensure_ascii=False))


def _partition(records, annotations, name, *, holdout_domain=None, seed=42):
    """Use frozen source splits; training seed never changes a frame's role."""
    selected = [row for row in records if row.frame_id in annotations.frames
                and annotations.frames[row.frame_id].split == name]
    if holdout_domain:
        target_groups = {row.group_id for row in records if row.domain == holdout_domain}
        selected = [row for row in selected if row.domain == holdout_domain] if name == 'test' else [
            row for row in selected if row.domain != holdout_domain and row.group_id not in target_groups]
    return selected


def _validate_annotation_protocol(records, annotations, protocol_dir):
    _, assignments, protocol = load_protocol(protocol_dir)
    for row in records:
        frame = annotations.frames.get(row.frame_id)
        if frame is None:
            continue
        if frame.group_id != row.group_id or frame.split != assignments[row.group_id]:
            raise ValueError(f'annotation split/group differs from frozen protocol: {row.frame_id}')
        if frame.source_anchor_hash != row.source_sha256:
            raise ValueError(f'annotation anchor differs from frozen source: {row.frame_id}')
    return protocol


def _attach_cache(records, index_path):
    from pallet.data.eligibility import active_policy
    control, _ = active_policy()
    if index_path and Path(index_path).resolve() == Path('outputs/cache_v5/sealed_index.json').resolve():
        index_path = control.get('cache_index', index_path)
    if not index_path or not Path(index_path).exists():
        return records
    index = json.loads(Path(index_path).read_text())
    if Path(index_path).name=='sealed_index.json':
        from pallet.data.loader import decoder_digest
        seal=json.loads(Path(index_path).with_name('seal.json').read_text())
        if seal['index_sha256']!=_sha256(index_path) or seal.get('decoder_sha256')!=decoder_digest():
            raise ValueError('cached tensor index or decoder identity changed')
    result=[]
    for row in records:
        entry=index.get(row.frame_id)
        result.append(replace(row,cache_path=entry.get('path') if isinstance(entry,dict) else entry,
                              cache_sha256=entry.get('sha256') if isinstance(entry,dict) else None))
    return result


def _check_source_provenance(records, annotations, target_domain):
    if not target_domain:
        return
    target_groups = {row.group_id for row in records if row.domain == target_domain}
    for row in records:
        if row.domain == target_domain:
            continue
        label = annotations.frames.get(row.frame_id)
        if label and any(target_groups.intersection(p.trained_group_ids) for p in label.provenance):
            raise ValueError(f"source label has target-trained proposal: {row.frame_id}")


def cmd_train(args):
    # Reject incomplete recipes before reading data or publishing run.json.
    from pallet.experiments.train import validate_training_recipe
    validate_training_recipe(args.recipe,args.family,size=args.size,
                             effective_batch=args.effective_batch,epochs=args.epochs,
                             patience=50,mosaic=args.mosaic,batch_size=args.batch_size)
    workers = getattr(args, 'workers', 0)
    validation_batch_size = getattr(args, 'validation_batch_size', 1)
    if workers < 0 or validation_batch_size < 1:
        raise ValueError('workers must be nonnegative and validation batch size positive')
    annotations = load_jsonl(args.annotations)
    manual_training_ids = set()
    manual_validation_ids = set()
    manual_annotation_scope = None
    human_manifest_sha256 = None
    human_validation_manifest_sha256 = None
    if args.human_annotations_manifest:
        from pallet.human_labeling import validate_human_training_manifest, is_auxiliary_manifest, AUXILIARY_SCOPE
        manual_manifest = json.loads(Path(args.human_annotations_manifest).read_text())
        human_training_ids = validate_human_training_manifest(
            args.human_annotations_manifest, manual_manifest, annotations, args.protocol)
        manual_training_ids = set(human_training_ids)
        human_manifest_sha256 = _sha256(args.human_annotations_manifest)
        if is_auxiliary_manifest(manual_manifest):
            manual_annotation_scope = AUXILIARY_SCOPE
    if args.human_validation_manifest:
        if not args.human_annotations_manifest:
            raise ValueError("manual validation requires a matching manual training manifest")
        from pallet.human_labeling import validate_human_validation_manifest
        validation_manifest = json.loads(Path(args.human_validation_manifest).read_text())
        from pallet.human_labeling import is_auxiliary_manifest
        if is_auxiliary_manifest(validation_manifest) != bool(manual_annotation_scope):
            raise ValueError('manual training and validation annotation scopes differ')
        manual_validation_ids = set(validate_human_validation_manifest(
            args.human_validation_manifest, validation_manifest, annotations,
            args.protocol, manual_training_ids))
        human_validation_manifest_sha256 = _sha256(args.human_validation_manifest)
    if manual_annotation_scope and not manual_validation_ids:
        raise ValueError('cross-split annotation assistance requires its group-held-out human validation manifest')
    records = _records(args.root, protocol_dir=args.protocol)
    protocol = _validate_annotation_protocol(records, annotations, args.protocol)
    _check_source_provenance(records, annotations, args.holdout_domain)
    records = _attach_cache(records, args.cache_index)
    if args.cohort == 'paired':
        records = [r for r in records if r.sensor_config and r.sensor_config.get('depth_available')]
    if args.no_intensity and args.cohort != 'paired':
        raise ValueError('depth-only comparison requires the common verified-depth paired cohort')
    if args.subset:
        ids = json.loads(Path(args.subset).read_text())
        if manual_validation_ids:
            if (set(ids.get('train', [])) != manual_training_ids
                    or set(ids.get('val', [])) != manual_validation_ids
                    or ids.get('test')):
                raise ValueError("manual partition selection differs from its bound manifests")
        selected = set(ids['train']) | set(ids['val'])
        records = [r for r in records if r.frame_id in selected]
    args.device = str(resolve_device(args.device))
    _check_source_provenance(records, annotations, args.holdout_domain)
    if manual_validation_ids:
        if args.holdout_domain or not args.subset:
            raise ValueError("manual validation mode requires its fixed subset and no domain holdout")
        records_by_id = {row.frame_id: row for row in records}
        if set(records_by_id) != manual_training_ids | manual_validation_ids:
            raise ValueError("manual partition source records are incomplete or contain extras")
        _, assignments, _ = load_protocol(args.protocol)
        for fid in manual_training_ids | manual_validation_ids:
            row = records_by_id[fid]
            if not manual_annotation_scope and assignments.get(row.group_id) != 'train':
                raise ValueError(f"manual assistant partition contains a nontraining source frame: {fid}")
        train_records = [records_by_id[fid] for fid in sorted(manual_training_ids)]
        val_records = [records_by_id[fid] for fid in sorted(manual_validation_ids)]
        train_groups = {row.group_id for row in train_records}
        val_groups = {row.group_id for row in val_records}
        if train_groups & val_groups:
            raise ValueError("manual validation split leaks acquisition groups into training")
    else:
        train_records = _partition(records, annotations, "train", holdout_domain=args.holdout_domain,
                                   seed=args.seed)
        val_records = _partition(records, annotations, "val", holdout_domain=args.holdout_domain,
                                 seed=args.seed)
    if args.holdout_domain:
        train_groups = {row.group_id for row in train_records}
        val_groups = {row.group_id for row in val_records}
        target_groups = {row.group_id for row in records if row.domain == args.holdout_domain}
        if train_groups & val_groups or train_groups & target_groups or val_groups & target_groups:
            raise ValueError("source train/val and held-out domain groups overlap")
    manual_ids = manual_training_ids | manual_validation_ids
    def reviewed(rows):
        return [row for row in rows if row.frame_id in annotations.frames
                and annotations.frames[row.frame_id].status in {"pos", "negative"}
                and (row.frame_id in manual_ids or is_resolved(
                    annotations.frames[row.frame_id],
                    require_blind=annotations.frames[row.frame_id].split in {'val','test'}))]

    usable = reviewed(train_records)
    validated = reviewed(val_records)
    pending = [row.frame_id for row in train_records + val_records
               if row.frame_id not in manual_ids
               if not is_resolved(annotations.frames[row.frame_id],
                                  require_blind=annotations.frames[row.frame_id].split == 'val')]
    if pending:
        raise ValueError(f'requested stage contains {len(pending)} unresolved reference frames; '
                         'use an explicit fully reviewed pilot/round subset')
    if not usable or not validated:
        raise ValueError("training needs independently reviewed source train and validation labels; "
                         f"found train={len(usable)}, validation={len(validated)}")
    normalization = fit_normalization(usable)
    pretrained = args.pretrained
    if args.scratch:
        pretrained = False if args.family == 'rfdetr-small' else None
    elif pretrained is None:
        pretrained = (True if args.family == "rfdetr-small" else
                      "yolov8s.pt" if args.family.startswith("yolov8") else "yolo26s.pt")
    output = Path(args.output)
    output.mkdir(parents=True, exist_ok=True)
    run_config = {"root": str(Path(args.root).resolve()),
                  "annotation_sha256": _sha256(args.annotations),
                  "human_annotations_manifest_sha256": human_manifest_sha256,
                  "human_validation_manifest_sha256": human_validation_manifest_sha256,
                  "manual_training_frames": sorted(manual_training_ids),
                  "manual_validation_frames": sorted(manual_validation_ids),
                  "validation_reference": ("user-confirmed held-out correction-archive annotations"
                      if manual_validation_ids else "independently reviewed machine annotations"),
                  "code_sha256":_code_fingerprint(),
                  "protocol_sha256": _sha256(Path(args.protocol) / 'protocol.json'),
                  "protocol": str(Path(args.protocol).resolve()),
                  "split_seed": protocol['split_seed'],
                  "subset_sha256": _sha256(args.subset) if args.subset else None,
                  "cache_index_sha256": _sha256(args.cache_index) if args.cache_index and Path(args.cache_index).exists() else None,
                  "pretrained": pretrained, "family": args.family,
                  "recipe": args.recipe,
                  "holdout_domain": args.holdout_domain,
                  "train_groups": sorted({row.group_id for row in train_records}),
                  "val_groups": sorted({row.group_id for row in val_records}),
                  "normalization": normalization.__dict__, "seed": args.seed,
                  "p2": args.family == "yolo26" and not args.no_p2,
                  "fusion": args.family == "yolo26" and not args.no_p2 and not args.no_fusion,
                  "edge": args.family == "yolo26" and not args.no_p2
                  and not args.no_edge and not args.no_depth,
                  "augmentation": not args.no_augment,
                  "mosaic": args.mosaic, "size": args.size,
                  "batch_size": args.batch_size, "effective_batch": args.effective_batch,
                  "epochs": args.epochs, "device_uuid": device_metadata(args.device).get('uuid'),
                  "use_depth": not args.no_depth, "use_intensity": not args.no_intensity}
    if manual_annotation_scope:
        run_config.update(manual_annotation_scope=manual_annotation_scope,
                          original_splits_preserved=True,
                          eligible_for_research_evaluation=False)
    run_config['cohort'] = args.cohort
    if workers or validation_batch_size != 1:
        run_config.update(workers=workers, validation_batch_size=validation_batch_size,
                          loader_policy='spawn_prefetch2_epoch_reseed_v1')
    if args.recipe=='official_research_constrained':
        from pallet.experiments.recipes import get_recipe_spec
        run_config['recipe_spec']=get_recipe_spec(args.family,args.recipe,batch_size=args.batch_size)
    from pallet.source_snapshot import snapshot_source
    run_config.update(snapshot_source())
    _record_run_config(output / "run.json", run_config)
    trained = train_yolo(train_records, val_records, annotations, normalization, output,
                         p2=not args.no_p2, use_fusion=not args.no_fusion,
                         use_edge=not args.no_edge,
                         use_depth=not args.no_depth, use_intensity=not args.no_intensity,
                         pretrained=pretrained, family=args.family,
                         seed=args.seed, epochs=args.epochs,
                         batch_size=args.batch_size, effective_batch=args.effective_batch,
                         device=args.device, size=args.size,
                         augmentation=not args.no_augment, mosaic=args.mosaic,
                         recipe=args.recipe, manual_training_ids=manual_training_ids,
                         manual_validation_ids=manual_validation_ids,
                         manual_annotation_scope=manual_annotation_scope,
                         workers=workers, validation_batch_size=validation_batch_size,
                         validation_reference=("user-confirmed held-out correction-archive annotations"
                             if manual_validation_ids else "independently reviewed machine annotations"))
    print(f"Best checkpoint: {trained}")


def cmd_evaluate(args):
    records = _records(args.root, protocol_dir=args.protocol)
    annotations = load_jsonl(args.annotations)
    _validate_annotation_protocol(records, annotations, args.protocol)
    reference_hash=None
    if args.reference_annotations:
        if args.split!='test':raise ValueError('separate reference snapshot is only supported for final held-out testing')
        refs=load_jsonl(args.reference_annotations)
        for fid,frame in refs.frames.items():
            original=annotations.frames.get(fid)
            if frame.split!='test' or original is None or original.split!='test':
                raise ValueError('reference snapshot attempts to modify source train/validation membership')
            if frame.group_id!=original.group_id or frame.source_anchor_hash!=original.source_anchor_hash:
                raise ValueError('new test reference does not match the frozen source identity')
            if not is_resolved(frame,require_blind=True):raise ValueError('test reference contains unresolved or assisted labels')
            annotations.frames[fid]=frame
        _validate_annotation_protocol(records,annotations,args.protocol)
        reference_hash=_sha256(args.reference_annotations)
    records = _attach_cache(records, args.cache_index)
    args.device = str(resolve_device(args.device))
    state = torch.load(args.checkpoint, map_location="cpu", weights_only=False)
    config = state["model_config"]
    if config.get("family") == "rfdetr-small":
        model = RFDETRDetector(resolution=config["size"], pretrained=False)
    else:
        model = PalletDetector(nc=1, p2=config["p2"], pretrained=None,
                               family=config.get("family", "yolo26"),
                               use_fusion=config.get("use_fusion", True),
                               use_edge=config["use_edge"], use_depth=config["use_depth"],
                               use_intensity=config["use_intensity"])
    model.load_state_dict(state["model"])
    run_file = Path(args.checkpoint).parent / "run.json"
    run = json.loads(run_file.read_text()) if run_file.exists() else {}
    if run.get('code_sha256') and run['code_sha256']!=_code_fingerprint():
        raise ValueError('evaluation code differs from registered training code; restore the recorded implementation')
    if run.get('protocol_sha256') != _sha256(Path(args.protocol) / 'protocol.json'):
        raise ValueError('checkpoint is not bound to the requested frozen data protocol')
    domain = run.get("holdout_domain")
    if run.get('cohort') == 'paired':
        records = [r for r in records if r.sensor_config and r.sensor_config.get('depth_available')]
    if run.get("annotation_sha256") and run["annotation_sha256"] != _sha256(args.annotations):
        raise ValueError("annotation snapshot changed since training; evaluate its frozen version")
    if run.get('subset_sha256') != (_sha256(args.subset) if args.subset else None):
        raise ValueError('evaluation stage subset differs from the trained stage')
    rows = _partition(records, annotations, args.split, holdout_domain=domain,
                      seed=run.get("split_seed", 42))
    if args.subset:
        subset = set(json.loads(Path(args.subset).read_text())[args.split])
        rows = [r for r in rows if r.frame_id in subset]
    coverage = {'requested_frames':len(rows),
                'ignored_frames':sum(annotations.frames[r.frame_id].status=='ignore' for r in rows)}
    if any(not is_resolved(annotations.frames[r.frame_id],require_blind=True) for r in rows):
        raise ValueError('evaluation stage still contains unresolved/non-blind reference frames')
    rows = [r for r in rows if reference_eligible(annotations.frames[r.frame_id])]
    stats = NormalizationStats(**state["normalization"])
    dataset = PalletDataset(rows, annotations, stats, size=config["size"])
    if not dataset:
        raise ValueError("evaluation has no independently reviewed reference frames")
    calibration = None
    if args.split == 'test':
        source_val = _partition(records, annotations, 'val', holdout_domain=domain)
        if args.subset:
            val_ids = set(json.loads(Path(args.subset).read_text())['val'])
            source_val = [r for r in source_val if r.frame_id in val_ids]
        calibration = PalletDataset(source_val, annotations, stats, size=config['size'])
        if not calibration:
            raise ValueError('test operating threshold requires independent source validation references')
    results = evaluate(model, dataset, device=args.device, calibration_dataset=calibration,
                       bootstrap_samples=args.bootstrap_samples)
    results['reference_coverage'] = {**coverage, 'scored_frames':len(dataset)}
    results["annotation_sha256"] = _sha256(args.annotations)
    results['independent_test_reference_sha256']=reference_hash
    results["checkpoint_sha256"] = _sha256(args.checkpoint)
    _write_json(args.output, results)
    print(json.dumps(results, ensure_ascii=False))


def cmd_predict(args):
    from pallet.export import load_detector_checkpoint
    args.device = str(resolve_device(args.device))

    record = next(row for row in _records(args.root, protocol_dir=args.protocol) if row.frame_id == args.frame_id)
    state = torch.load(args.checkpoint, map_location="cpu", weights_only=False)
    model, config = load_detector_checkpoint(args.checkpoint)
    model.to(args.device).eval()
    raw = load_frame(record)
    normalized = apply_normalization(raw, NormalizationStats(**state["normalization"]))
    image, scale, padding = letterbox_float(normalized, size=config["size"])
    meta = SampleMeta(record.frame_id, raw.shape[:2], scale, padding)
    boxes = predict_boxes(model, image.unsqueeze(0).to(args.device), meta,
                          conf=args.confidence, size=config["size"])
    result = {"frame_id": args.frame_id, "boxes": [
        {"class": "pallet", "xyxy": box, "confidence": score} for box, score in boxes]}
    if args.roi_out and record.pcd:
        import numpy as np
        _, points = read_pcd(record.pcd)
        if len(points) != raw.shape[0] * raw.shape[1]:
            raise ValueError("PCD ROI requires a confirmed pixel-aligned grid")
        cloud = points.reshape(raw.shape[0], raw.shape[1], 4)
        from pallet.data.orientation import orient_grid
        cloud = orient_grid(cloud, record.sensor_config)
        output = {}
        for idx, (box, _) in enumerate(boxes):
            x1, y1, x2, y2 = [int(round(v)) for v in box]
            roi = cloud[y1:y2, x1:x2].reshape(-1, 4)
            output[f"pallet_{idx}"] = roi[np.isfinite(roi[:, :3]).all(axis=1)]
        np.savez_compressed(args.roi_out, **output)
        result["roi_out"] = args.roi_out
    _write_json(args.output, result)
    print(json.dumps(result, ensure_ascii=False))


def cmd_export_model(args):
    from pallet.export import export_onnx

    print(json.dumps(export_onnx(args.checkpoint, args.output), ensure_ascii=False))


def build_parser():
    from pallet.data.eligibility import active_protocol, active_policy
    active_control, _ = active_policy()
    cache_default = active_control.get('cache_index', 'outputs/cache_v5/sealed_index.json')
    parser = argparse.ArgumentParser(prog="python -m pallet.cli")
    sub = parser.add_subparsers(dest="command", required=True)
    audit = sub.add_parser("audit")
    audit.add_argument("--root", default="/root/private/data/pallet")
    audit.add_argument("--output", default="outputs/dataset_audit.json")
    audit.set_defaults(func=cmd_audit)
    prepare = sub.add_parser("prepare")
    prepare.add_argument("--root", default="/root/private/data/pallet")
    prepare.add_argument("--output", default=str(Path(active_protocol())/'annotations_unreviewed.jsonl'))
    prepare.add_argument("--protocol", default=active_protocol())
    prepare.add_argument("--seed", type=int, default=42)
    prepare.set_defaults(func=cmd_prepare)
    dedup = sub.add_parser("dedup")
    dedup.add_argument("--root", default="/root/private/data/pallet")
    dedup.add_argument("--output", default="outputs/content_hashes.json")
    dedup.set_defaults(func=cmd_dedup)
    review = sub.add_parser("review")
    review.add_argument("--annotations", required=True)
    review.add_argument("--frame-id", required=True)
    review.add_argument("--reviewer", required=True)
    review.add_argument("--decision", choices=("approve", "reject", "needs_work"), required=True)
    review.add_argument("--status", choices=("pos", "negative", "ignore"))
    review.add_argument("--boxes", help="JSON list of pixel xywh boxes")
    review.add_argument("--note", default="")
    review.add_argument("--assisted", action="store_true", help="Reviewer saw train-frame proposals")
    review.set_defaults(func=cmd_review)
    imported = sub.add_parser("import-reviewed")
    imported.add_argument("--annotations", required=True)
    imported.add_argument("--review-file", required=True)
    imported.add_argument("--output", required=True)
    imported.set_defaults(func=cmd_import_reviewed)
    export = sub.add_parser("export")
    export.add_argument("--annotations", required=True)
    export.add_argument("--output", default="outputs/export")
    export.set_defaults(func=cmd_export_labels)
    propose = sub.add_parser("propose")
    propose.add_argument("--root", default="/root/private/data/pallet")
    propose.add_argument("--annotations", required=True)
    propose.add_argument("--split", choices=("train", "val", "test"), default="train")
    propose.add_argument("--limit", type=int)
    propose.add_argument("--device", default="cuda:0" if torch.cuda.is_available() else "cpu")
    propose.add_argument("--report", default="outputs/proposals_report.json")
    propose.set_defaults(func=cmd_propose)
    train = sub.add_parser("train")
    train.add_argument("--root", default="/root/private/data/pallet")
    train.add_argument("--protocol", default=active_protocol())
    train.add_argument("--subset", help="Frozen pilot or round JSON with train/val/test frame IDs")
    train.add_argument("--cache-index", default=cache_default)
    train.add_argument('--cohort',choices=('all','paired'),default='all')
    train.add_argument("--annotations", required=True)
    train.add_argument("--human-annotations-manifest",
                       help="Hashed source-training frames explicitly human-verified in a separate label snapshot")
    train.add_argument("--human-validation-manifest",
                       help="Hashed train.zip frames explicitly withheld by acquisition group for assistant-only validation")
    train.add_argument("--output", default="outputs/run")
    train.add_argument("--family", choices=("yolo26", "yolov8", "yolov8-cspnext",
                                           "rfdetr-small"), default="yolo26")
    train.add_argument("--recipe", choices=("project_adamw_pilot", "official_research_constrained",
                                            "official_default"), default="project_adamw_pilot",
                       help="Trainer recipe; constrained sensor recipe supports YOLO and RF-DETR")
    train.add_argument("--pretrained", default=None)
    train.add_argument('--scratch',action='store_true',help='Explicit random initialization for smoke/controlled ablation only')
    train.add_argument("--holdout-domain")
    train.add_argument("--seed", type=int, default=42)
    train.add_argument("--epochs", type=int, default=300)
    train.add_argument("--batch-size", type=int, default=4)
    train.add_argument("--effective-batch", type=int, default=16)
    train.add_argument('--workers', type=int, default=0)
    train.add_argument('--validation-batch-size', type=int, default=1)
    train.add_argument("--size", type=int, default=640)
    train.add_argument("--device", default="cuda:0" if torch.cuda.is_available() else "cpu")
    train.add_argument("--no-p2", action="store_true")
    train.add_argument("--no-fusion", action="store_true")
    train.add_argument("--no-edge", action="store_true")
    train.add_argument("--no-depth", action="store_true")
    train.add_argument("--no-intensity", action="store_true")
    train.add_argument("--no-augment", action="store_true")
    train.add_argument("--mosaic", action="store_true")
    train.set_defaults(func=cmd_train)
    val = sub.add_parser("evaluate")
    val.add_argument("--root", default="/root/private/data/pallet")
    val.add_argument("--protocol", default=active_protocol())
    val.add_argument("--subset")
    val.add_argument("--cache-index", default=cache_default)
    val.add_argument("--bootstrap-samples", type=int, default=0)
    val.add_argument("--annotations", required=True)
    val.add_argument('--reference-annotations',help='Optional independently frozen test-only reference, source labels remain unchanged')
    val.add_argument("--checkpoint", required=True)
    val.add_argument("--output", default="outputs/evaluation.json")
    val.add_argument("--split", choices=("val", "test"), default="test")
    val.add_argument("--device", default="cuda:0" if torch.cuda.is_available() else "cpu")
    val.set_defaults(func=cmd_evaluate)
    prediction = sub.add_parser("predict")
    prediction.add_argument("--root", default="/root/private/data/pallet")
    prediction.add_argument("--protocol", default=active_protocol())
    prediction.add_argument("--frame-id", required=True)
    prediction.add_argument("--checkpoint", required=True)
    prediction.add_argument("--output", default="outputs/prediction.json")
    prediction.add_argument("--roi-out")
    prediction.add_argument("--confidence", type=float, default=0.25)
    prediction.add_argument("--device", default="cuda:0" if torch.cuda.is_available() else "cpu")
    prediction.set_defaults(func=cmd_predict)
    model_export = sub.add_parser("export-model")
    model_export.add_argument("--checkpoint", required=True)
    model_export.add_argument("--output", required=True)
    model_export.set_defaults(func=cmd_export_model)
    return parser


def main():
    args = build_parser().parse_args()
    args.func(args)


if __name__ == "__main__":
    main()
