scripts/validate_mirror_parity.py

#!/usr/bin/env python3
"""Validate parity between the repo and prepared Hugging Face mirrors.

This is a publisher-side check. It compares critical website data, figures, and
validator scripts across the local repo, prepared HF Space bundle, prepared HF
artifact dataset bundle, and prepared HF model bundle before upload.
"""

from __future__ import annotations

import argparse
import hashlib
import json
from datetime import datetime, timezone
from pathlib import Path


ROOT = Path(__file__).resolve().parents[1]
DEFAULT_HF_ROOT = ROOT.parent / "hf_publish"
DEFAULT_OUTPUT = ROOT / "docs/data/mirror_parity.json"
QWEN3_FUTURE_TASK_PROBE_RUN_ID = "xperience10m_qwen3_omni_v6_future_task_probes_a100_20260616T143608Z"
QWEN3_RETRIEVAL_TASK_PROBE_RUN_IDS = [
    "xperience10m_qwen3_omni_v6_retrieval_task_probes_a100_20260617T175919Z",
    "xperience10m_qwen3_omni_v6_cross_modal_retrieval_probe_a100_20260618T000000Z",
    "xperience10m_qwen3_omni_v6_camera_view_sync_mosaic_tile_a100_20260619T0305Z",
    "xperience10m_qwen3_omni_v6_sensor_target_probes_a100_20260619T000000Z",
    "xperience10m_qwen3_omni_v6_interaction_text_task15_a100_20260620T010305Z",
]
COSMOS3_SUPER_RETRIEVAL_TASK_PROBE_RUN_IDS = [
    "xperience10m_cosmos3_super_retrieval_task_probes_a100_textonly_prompatch_v2_20260620",
    "xperience10m_cosmos3_nano_retrieval_task_probes_a100_patched_textonly_20260621",
]
COSMOS3_SUPER_FUTURE_TASK_PROBE_RUN_IDS = [
    "xperience10m_cosmos3_super_future_task_probes_a100_textonly_v1_20260620",
    "xperience10m_cosmos3_nano_future_order_misalignment_patched_textonly_20260621",
    "xperience10m_cosmos3_nano_current_subtask_object_relevance_patched_textonly_20260621",
]
COSMOS3_SUPER_INTERACTION_TEXT_TASK_PROBE_RUN_IDS = [
    "xperience10m_cosmos3_super_interaction_text_task15_textonly_v1_20260620T1558Z",
    "xperience10m_cosmos3_nano_interaction_text_task15_patched_textonly_20260621",
]

DATA_FILES = [
    "additional_development_directions.json",
    "audio_ablation_summary.json",
    "artifact_index.json",
    "brand_assets.json",
    "evidence_contract.json",
    "evaluation_protocol.json",
    "figure_index.json",
    "foundation_model_plan.json",
    "glossary.json",
    "live_publication_status.json",
    "language_versions.json",
    "modality_atlas.json",
    "omni_finetune_verified_result.json",
    "omni_model_comparison.json",
    "project_brief.json",
    "project_manifest.json",
    "project_packet.json",
    "public_reader_map.json",
    "project_status.json",
    "publication_audit.json",
    "public_surface_qa.json",
    "qwen3_full_parameter_gates.json",
    "qwen3_omni_run_lineage.json",
    "qwen3_v5_v6_comparison.json",
    "quality_gates.json",
    "raw_sample_files.json",
    "rendered_site_check.json",
    "reproducibility_matrix.json",
    "research_roadmap.json",
    "research_roadmap_interactive.json",
    "research_takeaways.json",
    "research_direction_extensions.json",
    "research_directions.json",
    "scope_claims_audit.json",
    "single_episode_explorer.json",
    "source_alignment_audit.json",
    "summary_metrics.json",
    "single_episode_task_model_radar.json",
    "episode128_task_model_radar.json",
    "three_foundation_pipelines.json",
    "two_evidence_lines.json",
    "two_evidence_line_result_summary.json",
    "task_suite_20.json",
    "task_suite_enhancement_128.json",
    "task_surface_integrity.json",
    "task_walkthroughs.json",
    "task_method_20_result_matrix.json",
    "task_method_20_gap_audit.json",
    "task_method_20_source_audit.json",
    "task_icon_manifest.json",
    "tier2_task_suite.json",
    "unified_task_model_radar.json",
    "website_integrity.json",
    "xperience10m_128_episode_feature_index.json",
    "xperience10m_dataset_card_alignment.json",
]

ASSET_FILES = [
    "charts/audio_ablation_delta.svg",
    "charts/two_evidence_line_map.svg",
    "charts/single_episode_task_model_radar.svg",
    "charts/episode128_task_model_radar.svg",
    "charts/tier2_task_suite.svg",
    "charts/unified_task_model_radar.svg",
    "charts/research_direction_coverage.svg",
    "brand/xperience10m-logo-apple-touch.png",
    "brand/xperience10m-logo-favicon-32.png",
    "brand/xperience10m-logo-favicon-64.png",
    "brand/xperience10m-logo-mark.png",
    "brand/xperience10m-logo-mark-192.png",
    "brand/xperience10m-logo-mark-512.png",
    "brand/xperience10m-logo-social-card.png",
    "task_suite_infographic.png",
    "pipeline_diagram.png",
    "pipeline_diagram.svg",
    "task_architectures.png",
    "task_architectures.svg",
    "task-icons/01_timeline_action.svg",
    "task-icons/02_timeline_subtask.svg",
    "task-icons/03_transition_detection.svg",
    "task-icons/04_next_action.svg",
    "task-icons/05_hand_trajectory_forecast.svg",
    "task-icons/06_contact_prediction.svg",
    "task-icons/07_object_relevance.svg",
    "task-icons/08_caption_grounding.svg",
    "task-icons/09_cross_modal_retrieval.svg",
    "task-icons/10_modality_reconstruction.svg",
    "task-icons/11_temporal_order.svg",
    "task-icons/12_misalignment_detection.svg",
    "task-icons/13_long_horizon_next_action.svg",
    "task-icons/14_next_subtask_forecast.svg",
    "task-icons/15_interaction_text_prediction.svg",
    "task-icons/16_action_object_relation.svg",
    "task-icons/17_object_set_forecast.svg",
    "task-icons/18_imu_to_hand_pose.svg",
    "task-icons/19_camera_view_sync_retrieval.svg",
    "task-icons/20_time_to_transition.svg",
    "task-icons/task-icon-atlas.png",
    "foundation-pipelines/spatial-intelligence-pipeline.png",
    "foundation-pipelines/human-video-world-model-pipeline.png",
    "foundation-pipelines/vision-language-action-pipeline.png",
    "foundation-pipelines/README.md",
    "foundation-pipelines/prompts.md",
    "foundation-pipelines/source-slides/spatial-intelligence-slide.png",
    "foundation-pipelines/source-slides/human-video-world-model-slide.png",
    "foundation-pipelines/source-slides/vision-language-action-slide.png",
    "foundation-pipelines/source-photos/spatial-intelligence-source.jpg",
    "foundation-pipelines/source-photos/human-video-world-model-source.jpg",
    "foundation-pipelines/source-photos/vision-language-action-source.jpg",
    "modalities/audio.png",
    "modalities/depth.jpg",
    "modalities/inertial.png",
    "modalities/language.png",
    "modalities/motion_capture.png",
    "modalities/pose_slam.png",
    "modalities/video.jpg",
    "raw-sample-preview/fisheye_cam0_preview.mp4",
    "raw-sample-preview/fisheye_cam0_poster.jpg",
    "raw-sample-preview/fisheye_cam1_preview.mp4",
    "raw-sample-preview/fisheye_cam1_poster.jpg",
    "raw-sample-preview/fisheye_cam2_preview.mp4",
    "raw-sample-preview/fisheye_cam2_poster.jpg",
    "raw-sample-preview/fisheye_cam3_preview.mp4",
    "raw-sample-preview/fisheye_cam3_poster.jpg",
    "raw-sample-preview/stereo_left_preview.mp4",
    "raw-sample-preview/stereo_left_poster.jpg",
    "raw-sample-preview/stereo_right_preview.mp4",
    "raw-sample-preview/stereo_right_poster.jpg",
]

SCRIPT_FILES = [
    "omni/analyze_qwen3_omni_errors.py",
    "omni/audit_staged_xperience10m_content.py",
    "omni/audit_cosmos3_super_training_contract.py",
    "omni/build_omni_model_comparison.py",
    "omni/build_qwen3_full_parameter_gate_summary.py",
    "omni/build_128_episode_feature_index.py",
    "omni/collect_qwen3_future_task_probe_results.sh",
    "omni/collect_qwen3_retrieval_task_probe_results.sh",
    "omni/collect_cosmos3_super_retrieval_task_probe_results.sh",
    "omni/collect_cosmos3_super_future_task_probe_results.sh",
    "omni/eval_cosmos3_super_interaction_text_task.py",
    "omni/collect_qwen3_v4_release_artifacts.py",
    "omni/defer_cosmos3_super_after_qwen_v4.sh",
    "omni/defer_qwen3_retrieval_after_order_sync.sh",
    "omni/defer_qwen3_fullparam_after_verified_qwen.sh",
    "omni/eval_qwen3_omni_future_task_probes.py",
    "omni/eval_qwen3_omni_retrieval_task_probes.py",
    "omni/eval_cosmos3_super_future_task_probes.py",
    "omni/eval_cosmos3_super_retrieval_task_probes.py",
    "omni/export_cosmos3_camera_pose_targets.py",
    "omni/launch_all_task_model_scoring_when_free.sh",
    "omni/merge_qwen3_omni_future_task_probe_shards.py",
    "omni/merge_qwen3_omni_retrieval_task_probe_shards.py",
    "omni/merge_cosmos3_super_future_task_probe_shards.py",
    "omni/merge_cosmos3_super_interaction_text_task_shards.py",
    "omni/pack_cosmos3_super_action_batch.py",
    "omni/prepare_cosmos3_super_lora_hf_package.py",
    "omni/prepare_qwen3_lora_hf_package.py",
    "omni/patch_qwen3_omni_video_features.py",
    "omni/probe_cosmos3_super_training_readiness.py",
    "omni/run_private_gpu_qwen3_v6_repro_smoke.sh",
    "omni/run_qwen3_omni_future_task_probes_sharded.sh",
    "omni/run_qwen3_omni_retrieval_task_probes_sharded.sh",
    "omni/run_cosmos3_super_future_task_probes_sharded.sh",
    "omni/run_cosmos3_super_retrieval_task_probes_sharded.sh",
    "omni/run_cosmos3_super_interaction_text_task_sharded.sh",
    "omni/score_existing_model_output_task_probes.py",
    "omni/score_model_output_probes.py",
    "omni/run_128_task_baselines.py",
    "omni/build_task_suite_enhancement_128.py",
    "omni/run_cosmos3_super_forward_dynamics_lora.sh",
    "omni/train_cosmos3_super_forward_dynamics_lora.py",
    "audio_ablation_and_raw_upgrade.py",
    "build_artifact_index.py",
    "build_brand_assets.py",
    "build_evaluation_protocol.py",
    "build_figure_index.py",
    "build_quality_gates.py",
    "build_qwen3_omni_run_lineage.py",
    "build_public_surface_qa.py",
    "build_rendered_site_check.py",
    "build_interactive_research_roadmap.py",
    "build_multilingual_public_readmes.py",
    "build_two_evidence_line_result_summary.py",
    "render_foundation_pipeline_diagrams.py",
    "build_single_episode_explorer.py",
    "build_task_method_20_gap_audit.py",
    "build_research_takeaways.py",
    "export_modality_atlas_assets.py",
    "generate_visualizations.py",
    "render_overview_figures.py",
    "render_task_suite_infographic.py",
    "research_direction_taxonomy.py",
    "task_display.py",
    "task_walkthroughs.py",
    "build_unified_task_suite.py",
    "build_unified_task_model_radar.py",
    "single_episode_diagnostics.py",
    "verify_live_publication.py",
    "validate_mirror_parity.py",
    "validate_publication_package.py",
    "validate_task_method_matrix_sources.py",
    "validate_scope_claims.py",
    "validate_source_alignment.py",
    "validate_task_surface.py",
    "validate_website_integrity.py",
    "sync_hf_publish_mirrors.py",
    "tier2_task_suite.py",
    "publish_hf_bundles.py",
]

WEBSITE_FILES = [
    "404.html",
    "apple-touch-icon.png",
    "favicon.png",
    "index.html",
    "research_roadmap.html",
    "single_episode_explorer.html",
    "site.webmanifest",
]

RESULT_FILES = [
    "audio_ablation/AUDIO_ABLATION_SUMMARY.md",
    "audio_ablation/audio_ablation_metrics.csv",
    "audio_ablation/audio_ablation_summary.json",
    "audio_ablation/audio_delta_summary.csv",
    "audio_ablation/raw_logmel_fisheye_cam0_sr16000_mels64_fft512_hop160.npz",
    "single_episode_diagnostics/provenance.json",
    "single_episode_diagnostics/README.md",
    "single_episode_diagnostics/modality_ablation/ablation_metrics.csv",
    "single_episode_diagnostics/modality_ablation/ablation_summary.json",
    "single_episode_diagnostics/object_labels/object_vocab.json",
    "single_episode_diagnostics/object_labels/window_object_labels.csv",
    "single_episode_diagnostics/timeline_overlay/timeline_overlay.csv",
    "single_episode_diagnostics/alignment_stress/alignment_shift_metrics.csv",
    "single_episode_diagnostics/alignment_stress/alignment_stress_summary.json",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/ERROR_ANALYSIS.md",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/error_analysis_summary.json",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/episode_error_analysis.csv",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/action_family_error_analysis.csv",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/train_seen_error_analysis.csv",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/missing_modality_error_analysis.csv",
    "omni_finetune/verified_public/xperience10m_qwen3_omni_128ep_96train_16val_16test_valmon_20260605_eval/analysis/object_category_error_analysis.csv",
    "omni_finetune/multi_episode_128_task_baselines/BASELINE_ALIGNMENT_REPORT.md",
    "omni_finetune/multi_episode_128_task_baselines/summary_report.json",
    "omni_finetune/multi_episode_128_task_baselines/task_metrics.csv",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/ENHANCEMENT_REPORT.md",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/dense_window_scenarios.csv",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/enhancement_plan.json",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/experiment_backlog.json",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/hierarchical_target_contract.json",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/qwen_action_family_error_summary.csv",
    "omni_finetune/task_suite_enhancement_128_v1_20260608/task_bottlenecks.csv",
    "omni_finetune/OMNI_MODEL_COMPARISON.md",
    "omni_finetune/MULTI_EPISODE_ACCESS_STATUS.md",
    "omni_finetune/XPERIENCE10M_128_DATA_PREPARATION_AND_FINETUNE_PLAN.md",
    "omni_finetune/QWEN3_FULL_PARAMETER_GATES_20260609.md",
    "omni_finetune/QWEN3_V5_V6_COMPARISON_20260614.md",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_smoke_preemptible_8gpu_20260609/fullparam_feasibility_summary.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_smoke_preemptible_8gpu_20260609/progress.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_smoke_preemptible_8gpu_20260609/training_metadata.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_smoke_preemptible_8gpu_20260609/RUN_REPORT.md",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_shorttrain8_preemptible_8gpu_20260609/fullparam_shorttrain8_summary.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_shorttrain8_preemptible_8gpu_20260609/progress.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_shorttrain8_preemptible_8gpu_20260609/launch_status.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot32_preemptible_8gpu_20260609/fullparam_pilot32_summary.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot32_preemptible_8gpu_20260609/progress.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot32_preemptible_8gpu_20260609/launch_status.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot64_preemptible_8gpu_20260609/fullparam_pilot64_summary.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot64_preemptible_8gpu_20260609/progress.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot64_preemptible_8gpu_20260609/training_metadata.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot64_preemptible_8gpu_20260609/RUN_REPORT.md",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot64_preemptible_8gpu_20260609/config.yaml",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot64_preemptible_8gpu_20260609/launch_status.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_preemptible_8gpu_20260609/fullparam_pilot128_summary.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_preemptible_8gpu_20260609/progress.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_preemptible_8gpu_20260609/launch_status.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_after_qwen_v5_preemptible_8gpu_20260609/progress.jsonl",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_after_qwen_v5_preemptible_8gpu_20260609/config.yaml",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_after_qwen_v5_preemptible_8gpu_20260609/training_metadata.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_after_qwen_v5_preemptible_8gpu_20260609/RUN_REPORT.md",
    "omni_finetune/xperience10m_qwen3_omni_128ep_fullparam_pilot128_after_qwen_v5_preemptible_8gpu_20260609/launch_status.jsonl",
    "omni_finetune/HF_UPLOAD.md",
    "omni_finetune/model_output_probe_readiness/model_output_probe_readiness.json",
    "omni_finetune/model_output_probe_readiness/RUN_REPORT.md",
    "omni_finetune/xperience10m_cosmos3_super_training_readiness_20260607/training_readiness.json",
    "omni_finetune/xperience10m_cosmos3_super_training_readiness_20260607/RUN_REPORT.md",
    "omni_finetune/xperience10m_cosmos3_super_training_readiness_metadata_a100_20260609/training_readiness.json",
    "omni_finetune/xperience10m_cosmos3_super_training_readiness_metadata_a100_20260609/RUN_REPORT.md",
    "omni_finetune/xperience10m_cosmos3_super_training_contract_audit_camera_pose_20260608/training_contract_audit.json",
    "omni_finetune/xperience10m_cosmos3_super_training_contract_audit_camera_pose_20260608/RUN_REPORT.md",
    "omni_finetune/xperience10m_cosmos3_super_action_packer_schema_smoke_20260608/packer_summary.json",
    "omni_finetune/xperience10m_cosmos3_super_action_packer_schema_smoke_20260608/RUN_REPORT.md",
    "omni_finetune/xperience10m_cosmos3_camera_pose_targets_20260608/target_manifest.json",
    "omni_finetune/xperience10m_cosmos3_super_training_contract_audit_20260608/RUN_REPORT.md",
    "omni_finetune/xperience10m_cosmos3_super_training_contract_audit_20260608/training_contract_audit.json",
    "omni_finetune/xperience10m_cosmos3_super_training_contract_audit_20260608/training_metadata.json",
    "omni_finetune/xperience10m_cosmos3_super_training_contract_audit_camera_pose_20260608/training_metadata.json",
    "omni_finetune/xperience10m_qwen3_omni_128ep_structured_json_v3_strict_label_prompt_reuse_lora_eval_test_full/analysis/ERROR_ANALYSIS.md",
    "omni_finetune/xperience10m_qwen3_omni_128ep_structured_json_v3_strict_label_prompt_reuse_lora_eval_test_full/analysis/error_analysis_summary.json",
    "omni_finetune/verified_public/xperience10m_cosmos3_nano_128ep_future_window_h5_compat_adapter_eval_test_full/verified_result_summary.json",
    "omni_finetune/verified_public/xperience10m_cosmos3_nano_128ep_future_window_h5_compat_adapter_eval_test_full/PUBLIC_RESULT_SUMMARY.md",
    "omni_finetune/verified_public/xperience10m_cosmos3_nano_128ep_future_window_h5_compat_adapter_eval_test_full/eval/metrics.json",
    "omni_finetune/verified_public/xperience10m_cosmos3_nano_128ep_future_window_h5_compat_adapter_eval_test_full/eval/RUN_REPORT.md",
]

DOC_FILES = [
    "README.zh.md",
    "README.es.md",
    "README.fr.md",
    "README.de.md",
    "README.ja.md",
    "README.ko.md",
    "README.pt.md",
    "ARTIFACT_GUIDE.md",
    "OMNI_MODEL_EXTENSION_CONTRACT.md",
    "QUALITY_GATES.md",
    "EVALUATION_PROTOCOL.md",
    "FIGURE_INDEX.md",
    "FOUNDATION_MODEL_PLAN.md",
    "GLOSSARY.md",
    "ADDITIONAL_DEVELOPMENT_DIRECTIONS.md",
    "THREE_FOUNDATION_PIPELINES.md",
    "TWO_EVIDENCE_LINES.md",
    "TWO_EVIDENCE_LINE_RESULT_SUMMARY.md",
    "QWEN3_OMNI_RUN_LINEAGE.md",
    "PROJECT_BRIEF.md",
    "PUBLIC_READER_MAP.md",
    "RENDERED_SITE_CHECK.md",
    "RESEARCH_ROADMAP.md",
    "PROJECT_STATUS.md",
    "REPRODUCIBILITY.md",
    "TASK_SUITE_ENHANCEMENT_128.md",
    "XPERIENCE10M_128_EPISODE_FEATURE_INDEX.md",
    "TASK_METHOD_20_GAP_AUDIT.md",
    "TASK_METHOD_20_RESULT_MATRIX.md",
    "TASK_SUITE_20.md",
    "PUBLIC_SURFACE_QA.md",
    "EVIDENCE_CONTRACT.md",
    "RESEARCH_TAKEAWAYS.md",
    "SOURCE_ALIGNMENT_AUDIT.md",
    "XPERIENCE_EMBODIED_FOUNDATION_MODEL_PRETRAINING.md",
    "XPERIENCE10M_DATASET_CARD_ALIGNMENT.md",
]


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


def display_path(path: Path, hf_root: Path) -> str:
    resolved = path.resolve()
    bases = [
        ("hf_space", hf_root / "space"),
        ("hf_artifacts", hf_root / "artifacts"),
        ("hf_model", hf_root / "model"),
        ("repo", ROOT),
        ("hf_publish", hf_root),
    ]
    for label, base in bases:
        try:
            return f"{label}:{resolved.relative_to(base.resolve()).as_posix()}"
        except ValueError:
            continue
    return path.name


def file_record(path: Path, hf_root: Path) -> dict:
    record = {
        "path": display_path(path, hf_root),
        "exists": path.exists(),
    }
    if path.exists() and path.is_file():
        record["bytes"] = path.stat().st_size
        record["sha256"] = sha256(path)
    else:
        record["bytes"] = 0
        record["sha256"] = None
    return record


def verified_public_result_files() -> list[str]:
    """Return every public-safe file from verified model packages.

    Verified packages are already sanitized by the package audit; mirroring the
    whole package prevents final model results from being silently omitted when a
    new run lands under results/omni_finetune/verified_public.
    """

    verified_root = ROOT / "results/omni_finetune/verified_public"
    if not verified_root.exists():
        return []
    files: list[str] = []
    for path in verified_root.rglob("*"):
        if not path.is_file():
            continue
        files.append(path.relative_to(ROOT / "results").as_posix())
    return sorted(files)


def tier2_result_files() -> list[str]:
    """Return every generated public-safe artifact for the historical provenance bundle.

    The directory name is historical and kept for stable public links.
    """

    tier2_root = ROOT / "results/episode_task_suite/tier2_task_suite"
    if not tier2_root.exists():
        return []
    files: list[str] = []
    for path in tier2_root.rglob("*"):
        if path.is_file():
            files.append(path.relative_to(ROOT / "results").as_posix())
    return sorted(files)


def a100_128_metadata_result_files() -> list[str]:
    """Return the public-safe 128-episode metadata baseline rerun artifacts."""

    result_root = ROOT / "results/omni_finetune/a100_128_metadata_task_baselines_20260616_v2"
    if not result_root.exists():
        return []
    files: list[str] = []
    for path in result_root.rglob("*"):
        if path.is_file():
            files.append(path.relative_to(ROOT / "results").as_posix())
    return sorted(files)


def a100_128_raw20_result_files() -> list[str]:
    """Return public-safe 128-episode raw-feature 20-task baseline artifacts."""

    result_root = ROOT / "results/omni_finetune/a100_128_raw20_task_baselines_complete20_proxy_20260616T091500Z"
    if not result_root.exists():
        return []
    files: list[str] = []
    for path in result_root.rglob("*"):
        if path.is_file():
            files.append(path.relative_to(ROOT / "results").as_posix())
    return sorted(files)


def xperience10m_128_data_feature_files() -> list[str]:
    """Return selected 128-episode source and processed-feature artifacts."""

    explicit = [
        ROOT / "results/omni_finetune/xperience10m_128_episode_selection.json",
        ROOT / "results/omni_finetune/xperience10m_128_episode_selection.csv",
        ROOT / "results/omni_finetune/xperience10m_128_episode_download_files.txt",
        ROOT / "results/omni_finetune/episode_manifest.json",
        ROOT / "results/omni_finetune/dataset_manifest.json",
        ROOT / "results/omni_finetune/multi_episode_128_task_baselines/metadata_feature_matrix.npz",
        ROOT / "results/omni_finetune/a100_128_metadata_task_baselines_20260616_v2/metadata_feature_matrix.npz",
    ]
    dense_root = ROOT / "results/omni_finetune/xperience10m_128ep_dense_multiscale_hierarchical_v1_20260608"
    files: list[str] = []
    for path in explicit:
        if path.is_file():
            files.append(path.relative_to(ROOT / "results").as_posix())
    if dense_root.exists():
        for path in dense_root.rglob("*"):
            if path.is_file():
                files.append(path.relative_to(ROOT / "results").as_posix())
    return sorted(set(files))


def model_output_task_probe_result_files() -> list[str]:
    """Return task-specific scores derived from existing verified model outputs."""

    result_root = ROOT / "results/omni_finetune/model_output_task_probes_20260616"
    if not result_root.exists():
        return []
    files: list[str] = []
    for path in result_root.rglob("*"):
        if path.is_file():
            files.append(path.relative_to(ROOT / "results").as_posix())
    return sorted(files)


def qwen3_future_task_probe_result_files() -> list[str]:
    """Return public-safe Qwen3 future-task probe outputs from the shard run."""

    result_root = ROOT / "results/omni_finetune" / QWEN3_FUTURE_TASK_PROBE_RUN_ID
    files: list[str] = []
    if result_root.exists():
        for path in result_root.rglob("*"):
            if path.is_file():
                files.append(path.relative_to(ROOT / "results").as_posix())

    launcher_log = (
        ROOT
        / "results/omni_finetune/deferred_launchers"
        / f"{QWEN3_FUTURE_TASK_PROBE_RUN_ID}.launcher.log"
    )
    if launcher_log.is_file():
        files.append(launcher_log.relative_to(ROOT / "results").as_posix())
    return sorted(files)


def qwen3_retrieval_task_probe_result_files() -> list[str]:
    """Return public-safe Qwen3 retrieval probe outputs from task 08/09 runs."""

    files: list[str] = []
    for run_id in QWEN3_RETRIEVAL_TASK_PROBE_RUN_IDS:
        result_root = ROOT / "results/omni_finetune" / run_id
        if result_root.exists():
            for path in result_root.rglob("*"):
                if path.is_file():
                    files.append(path.relative_to(ROOT / "results").as_posix())

        launch_log = ROOT / "results/omni_finetune/deferred_launchers" / f"{run_id}.launch.log"
        if launch_log.is_file():
            files.append(launch_log.relative_to(ROOT / "results").as_posix())
        direct_launch_log = ROOT / "results/omni_finetune/deferred_launchers" / f"{run_id}.launcher.log"
        if direct_launch_log.is_file():
            files.append(direct_launch_log.relative_to(ROOT / "results").as_posix())
    return sorted(set(files))


def cosmos3_super_retrieval_task_probe_result_files() -> list[str]:
    """Return public-safe Cosmos3-Super retrieval probe outputs."""

    files: list[str] = []
    compact_names = {"RUN_REPORT.md", "collection_validation.json", "metrics.json", "server_info.json", "summary.json"}
    for run_id in COSMOS3_SUPER_RETRIEVAL_TASK_PROBE_RUN_IDS:
        result_root = ROOT / "results/omni_finetune" / run_id
        if result_root.exists():
            for path in result_root.rglob("*"):
                if path.is_file() and (path.name in compact_names or path.name.endswith(".progress.jsonl")):
                    files.append(path.relative_to(ROOT / "results").as_posix())

        for suffix in ("launch", "launcher", "retrieval", "runner"):
            launch_log = ROOT / "results/omni_finetune/deferred_launchers" / f"{run_id}.{suffix}.log"
            if launch_log.is_file():
                files.append(launch_log.relative_to(ROOT / "results").as_posix())
    return sorted(set(files))


def cosmos3_super_future_task_probe_result_files() -> list[str]:
    """Return public-safe Cosmos3-Super future-task probe outputs."""

    files: list[str] = []
    compact_names = {
        "RUN_REPORT.md",
        "collection_validation.json",
        "metrics.json",
        "per_class_metrics.csv",
        "server_info.json",
        "summary.json",
    }
    for run_id in COSMOS3_SUPER_FUTURE_TASK_PROBE_RUN_IDS:
        result_root = ROOT / "results/omni_finetune" / run_id
        if result_root.exists():
            for path in result_root.rglob("*"):
                if path.is_file() and (path.name in compact_names or path.name.endswith(".progress.jsonl")):
                    files.append(path.relative_to(ROOT / "results").as_posix())

        for suffix in ("launch", "launcher", "runner"):
            launch_log = ROOT / "results/omni_finetune/deferred_launchers" / f"{run_id}.{suffix}.log"
            if launch_log.is_file():
                files.append(launch_log.relative_to(ROOT / "results").as_posix())
    return sorted(set(files))


def cosmos3_super_interaction_text_task_probe_result_files() -> list[str]:
    """Return public-safe Cosmos3-Super task-15 interaction-text probe outputs."""

    files: list[str] = []
    compact_names = {
        "RUN_REPORT.md",
        "collection_validation.json",
        "confusion_matrix.csv",
        "launch_env.txt",
        "metrics.json",
        "per_class_metrics.csv",
        "server_info.json",
        "summary.json",
    }
    for run_id in COSMOS3_SUPER_INTERACTION_TEXT_TASK_PROBE_RUN_IDS:
        result_root = ROOT / "results/omni_finetune" / run_id
        if result_root.exists():
            for path in result_root.rglob("*"):
                if path.is_file() and (path.name in compact_names or path.name.endswith(".progress.jsonl")):
                    files.append(path.relative_to(ROOT / "results").as_posix())

        for suffix in ("launch", "launcher", "runner"):
            launch_log = ROOT / "results/omni_finetune/deferred_launchers" / f"{run_id}.{suffix}.log"
            if launch_log.is_file():
                files.append(launch_log.relative_to(ROOT / "results").as_posix())
    return sorted(set(files))


def parity_group(name: str, local_path: Path, mirrors: dict[str, Path], hf_root: Path) -> dict:
    local = file_record(local_path, hf_root)
    mirror_records = {surface: file_record(path, hf_root) for surface, path in mirrors.items()}
    failures = []
    if not local["exists"]:
        failures.append({"surface": "repo", "kind": "missing", "path": local["path"]})
    for surface, record in mirror_records.items():
        if not record["exists"]:
            failures.append({"surface": surface, "kind": "missing", "path": record["path"]})
            continue
        if local["exists"] and record["sha256"] != local["sha256"]:
            failures.append(
                {
                    "surface": surface,
                    "kind": "hash_mismatch",
                    "path": record["path"],
                    "expected_sha256": local["sha256"],
                    "actual_sha256": record["sha256"],
                }
            )
    return {
        "name": name,
        "status": "pass" if not failures else "fail",
        "local": local,
        "mirrors": mirror_records,
        "failures": failures,
    }


def build_report(hf_root: Path) -> dict:
    groups = []

    for filename in DATA_FILES:
        groups.append(
            parity_group(
                f"data/{filename}",
                ROOT / "docs/data" / filename,
                {
                    "hf_space": hf_root / "space/data" / filename,
                    "hf_artifacts_data": hf_root / "artifacts/data" / filename,
                    "hf_artifacts": hf_root / "artifacts/docs/data" / filename,
                    "hf_model_data": hf_root / "model/data" / filename,
                    "hf_model_docs_data": hf_root / "model/docs/data" / filename,
                    "hf_model": hf_root / "model/metrics" / filename,
                },
                hf_root,
            )
        )

    for filename in ASSET_FILES:
        groups.append(
            parity_group(
                f"assets/{filename}",
                ROOT / "docs/assets" / filename,
                {
                    "hf_space": hf_root / "space/assets" / filename,
                    "hf_artifacts_docs": hf_root / "artifacts/docs/assets" / filename,
                    "hf_artifacts_card": hf_root / "artifacts/assets" / filename,
                    "hf_model": hf_root / "model/assets" / filename,
                },
                hf_root,
            )
        )

    for filename in SCRIPT_FILES:
        groups.append(
            parity_group(
                f"scripts/{filename}",
                ROOT / "scripts" / filename,
                {
                    "hf_artifacts": hf_root / "artifacts/scripts" / filename,
                    "hf_model": hf_root / "model/scripts" / filename,
                },
                hf_root,
            )
        )

    for filename in WEBSITE_FILES:
        groups.append(
            parity_group(
                f"website/{filename}",
                ROOT / "docs" / filename,
                {
                    "hf_space": hf_root / "space" / filename,
                    "hf_artifacts_root": hf_root / "artifacts" / filename,
                    "hf_artifacts_docs": hf_root / "artifacts/docs" / filename,
                    "hf_model": hf_root / "model" / filename,
                    "hf_model_docs": hf_root / "model/docs" / filename,
                },
                hf_root,
            )
        )

    result_files = sorted(
        set(RESULT_FILES)
        | set(verified_public_result_files())
        | set(tier2_result_files())
        | set(a100_128_metadata_result_files())
        | set(a100_128_raw20_result_files())
        | set(xperience10m_128_data_feature_files())
        | set(model_output_task_probe_result_files())
        | set(qwen3_future_task_probe_result_files())
        | set(qwen3_retrieval_task_probe_result_files())
        | set(cosmos3_super_retrieval_task_probe_result_files())
        | set(cosmos3_super_future_task_probe_result_files())
        | set(cosmos3_super_interaction_text_task_probe_result_files())
    )
    for filename in result_files:
        groups.append(
            parity_group(
                f"results/{filename}",
                ROOT / "results" / filename,
                {
                    "hf_artifacts": hf_root / "artifacts/results" / filename,
                    "hf_model": hf_root / "model/results" / filename,
                },
                hf_root,
            )
        )

    space_result_files = sorted(
        set(RESULT_FILES)
        | set(tier2_result_files())
        | set(model_output_task_probe_result_files())
        | set(qwen3_future_task_probe_result_files())
        | set(qwen3_retrieval_task_probe_result_files())
        | set(cosmos3_super_retrieval_task_probe_result_files())
        | set(cosmos3_super_future_task_probe_result_files())
        | set(cosmos3_super_interaction_text_task_probe_result_files())
    )
    for filename in space_result_files:
        groups.append(
            parity_group(
                f"space_results/{filename}",
                ROOT / "results" / filename,
                {
                    "hf_space": hf_root / "space/results" / filename,
                },
                hf_root,
            )
        )

    for filename in DOC_FILES:
        groups.append(
            parity_group(
                f"docs/{filename}",
                ROOT / filename,
                {
                    "hf_space": hf_root / "space" / filename,
                    "hf_artifacts": hf_root / "artifacts" / filename,
                    "hf_model": hf_root / "model" / filename,
                },
                hf_root,
            )
        )

    failures = [
        {"group": group["name"], **failure}
        for group in groups
        for failure in group["failures"]
    ]
    by_surface: dict[str, int] = {}
    for failure in failures:
        by_surface[failure["surface"]] = by_surface.get(failure["surface"], 0) + 1

    return {
        "status": "pass" if not failures else "fail",
        "generated_at_utc": datetime.now(timezone.utc).isoformat(timespec="seconds"),
        "hf_root": "hf_publish",
        "summary": {
            "group_count": len(groups),
            "failure_count": len(failures),
            "failures_by_surface": by_surface,
        },
        "checks": [
            {
                "name": "repo_hf_space_artifact_model_data_parity",
                "status": "pass"
                if not any(failure["group"].startswith("data/") for failure in failures)
                else "fail",
            },
            {
                "name": "repo_hf_visual_asset_parity",
                "status": "pass"
                if not any(failure["group"].startswith("assets/") for failure in failures)
                else "fail",
            },
            {
                "name": "repo_hf_validator_script_parity",
                "status": "pass"
                if not any(failure["group"].startswith("scripts/") for failure in failures)
                else "fail",
            },
            {
                "name": "repo_hf_website_html_parity",
                "status": "pass"
                if not any(failure["group"].startswith("website/") for failure in failures)
                else "fail",
            },
            {
                "name": "repo_hf_diagnostic_result_parity",
                "status": "pass"
                if not any(failure["group"].startswith("results/") for failure in failures)
                else "fail",
            },
            {
                "name": "repo_hf_quality_doc_parity",
                "status": "pass"
                if not any(failure["group"].startswith("docs/") for failure in failures)
                else "fail",
            },
        ],
        "groups": groups,
        "failures": failures,
    }


def main() -> int:
    parser = argparse.ArgumentParser()
    parser.add_argument("--hf-root", type=Path, default=DEFAULT_HF_ROOT)
    parser.add_argument("--output", type=Path, default=DEFAULT_OUTPUT)
    args = parser.parse_args()

    report = build_report(args.hf_root.resolve())
    args.output.parent.mkdir(parents=True, exist_ok=True)
    args.output.write_text(json.dumps(report, indent=2) + "\n", encoding="utf-8")
    print(f"{report['status'].upper()}: wrote {args.output}")
    if report["status"] != "pass":
        for failure in report["failures"][:40]:
            print(f"- {failure['group']}: {failure['surface']} {failure['kind']} {failure['path']}")
        if len(report["failures"]) > 40:
            print(f"- ... {len(report['failures']) - 40} more failures")
        return 1
    return 0


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