#!/usr/bin/env python3
"""Compare saved proposals on a fixed, never manually reviewed frame cohort.

No training labels, independent reference boxes, or GPU inference are used.
Kept outside pallet/ so this analysis does not change a running trainer's source
fingerprint. Missing receipts are errors, never interpreted as empty detections.
"""
import argparse
from collections import Counter, defaultdict
import csv
from datetime import datetime
import hashlib
import itertools
import json
import os
from pathlib import Path
import time
from zoneinfo import ZoneInfo

# Analysis is a CPU task alongside GPU training; avoid taking all loader cores.
os.environ.setdefault('OPENBLAS_NUM_THREADS', '1')
os.environ.setdefault('OMP_NUM_THREADS', '1')
import numpy as np
from scipy.optimize import linear_sum_assignment


METHOD = {
    'matching': 'maximum cardinality one-to-one IoU>=0.50, then maximum IoU sum',
    'match_iou': 0.50,
    'stable_iou': 0.95,
    'sensitivity_stable_iou': 0.90,
    'max_edge_shift_short_side': 0.02,
    'substantive_change': 'any added/deleted box or matched IoU<0.95 or edge shift>2% native short side',
    'common_confidence': 'maximum saved confidence floor across compared rounds; no lower candidates reconstructed',
    'bootstrap': '2000 resamples of whole collection groups, frame-weighted ratio, seed42',
    'operational_convergence': 'both adjacent pairs: <1% changed frames and <1% changed nonempty frames; both group bootstrap upper bounds <1%',
    'no_ground_truth_scoring': True,
    'stable_does_not_mean_correct': True,
}


def read(path):
    return json.loads(Path(path).read_text())


def digest(path):
    h = hashlib.sha256()
    with Path(path).open('rb') as stream:
        for block in iter(lambda: stream.read(4 * 1024**2), b''):
            h.update(block)
    return h.hexdigest()


def json_digest(value):
    return hashlib.sha256(json.dumps(value, sort_keys=True, ensure_ascii=False).encode()).hexdigest()


def write(path, value):
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_suffix(path.suffix + '.tmp')
    temporary.write_text(json.dumps(value, indent=2, ensure_ascii=False, allow_nan=False) + '\n')
    temporary.replace(path)


def slug(fid):
    return hashlib.sha256(fid.encode()).hexdigest()[:24]


def require(condition, message):
    if not condition:
        raise ValueError(message)


def partition(path, protocol_sha):
    p = read(path / 'manual_partition.json')
    require(p['protocol_sha256'] == protocol_sha, f'Partition protocol mismatch: {path}')
    train, val = set(p['train_frame_ids']), set(p['validation_frame_ids'])
    manual = set(p['all_manual_frame_ids'])
    require(not train & val and train | val == manual, f'Invalid manual partition: {path}')
    require(len(manual) == len(p['all_manual_frame_ids']), f'Duplicate manual IDs: {path}')
    require(not set(p['train_groups']) & set(p['validation_groups']), f'Group overlap: {path}')
    for name, expected in p['artifact_sha256'].items():
        require(digest(path / name) == expected, f'Manual artifact changed: {path / name}')
    require(digest(path / 'inputs/annotations.jsonl') == p['manual_annotations_sha256'],
            f'Manual label snapshot changed: {path}')
    return p, manual


def cohort(source, excluded):
    index = {}
    for line in (source / 'frames.jsonl').read_text().splitlines():
        row = json.loads(line)
        require(row['frame_id'] not in index, 'Duplicate source frame ID')
        index[row['frame_id']] = row
    require(excluded <= set(index), 'Manual frame missing from source export')
    remaining = {fid: row for fid, row in index.items() if fid not in excluded}
    require(remaining, 'Empty comparison cohort')
    require(len({slug(fid) for fid in index}) == len(index), 'Frame filename hash collision')
    return index, remaining


def prepare(args):
    protocol_sha = digest(args.protocol / 'protocol.json')
    latest_partition, excluded = partition(args.manual_output, protocol_sha)
    index, remaining = cohort(args.source_export, excluded)
    rounds, parts = [], []
    previous = set()
    for specification in args.round:
        name, separator, location = specification.partition('=')
        require(separator and name, 'Use --round NAME=OUTPUT_DIRECTORY')
        path = Path(location).resolve()
        p, ids = partition(path, protocol_sha)
        require(previous <= ids <= excluded, 'Manual cohorts must be chronological and nested')
        require(not ids & set(remaining), 'Manually reviewed frame entered stability comparison')
        require(ids <= set(index), 'Round contains unknown manual IDs')
        rounds.append((name, path, ids))
        parts.append({'name': name, 'output': str(path), 'manual_frames': len(ids),
                      'partition_sha256': digest(path / 'manual_partition.json'),
                      'manual_snapshot_sha256': p['manual_annotations_sha256']})
        previous = ids
    require(len(set(name for name, _, _ in rounds)) == len(rounds), 'Duplicate round name')
    require(len(rounds) >= 2, 'At least two rounds required')
    task = {'method': METHOD, 'rounds': parts, 'expected_rounds': args.expected_rounds,
            'latest_manual_partition_sha256': digest(args.manual_output / 'manual_partition.json'),
            'excluded_manual_frames': len(excluded), 'remaining_frames': len(remaining),
            'split_counts': dict(Counter(row['split'] for row in remaining.values())),
            'remaining_frame_ids_sha256': json_digest(sorted(remaining)),
            'protocol_sha256': protocol_sha,
            'source_export_manifest_sha256': digest(args.source_export / 'manifest.json'),
            'source_frame_index_sha256': digest(args.source_export / 'frames.jsonl'),
            'analysis_source_sha256': digest(Path(__file__)),
            'manual_snapshot_sha256': latest_partition['manual_annotations_sha256']}
    args.output.mkdir(parents=True, exist_ok=True)
    task_path = args.output / 'task.json'
    if task_path.exists():
        require(read(task_path) == task, 'Stability task input/method changed; use a new output directory')
    else:
        write(task_path, task)
    return rounds, index, remaining, task


def validate_receipt(row, source, binding, floor):
    width, height = source['size']
    for key in ('frame_id', 'group_id', 'split', 'domain', 'source_anchor_hash'):
        require(row.get(key) == source[key], f'Receipt {key} mismatch for {source["frame_id"]}')
    require((row.get('width'), row.get('height')) == (width, height), 'Receipt dimensions changed')
    require(row.get('binding') == binding, 'Receipt provenance binding mismatch')
    require(row.get('checkpoint_sha256') == binding['checkpoint_sha256']
            and row.get('threshold_sha256') == binding['threshold_sha256'], 'Receipt model/threshold changed')
    require(row.get('human_reviewed') is False and row.get('proposal_only') is True,
            'Receipt claims to be manually reviewed')
    boxes = row['boxes_xyxy_score']
    expected_status = 'proposal' if boxes else 'zero_detection_unreviewed'
    require(row['status'] == expected_status, 'Receipt status conflicts with boxes')
    for box in boxes:
        xyxy = box['xyxy']
        require(len(xyxy) == 4 and np.isfinite(xyxy).all(), 'Invalid box coordinates')
        x1, y1, x2, y2 = xyxy
        require(0 <= x1 < x2 <= width and 0 <= y1 < y2 <= height, 'Out-of-bounds box')
        require(np.isfinite(box['score']) and floor - 1e-6 <= box['score'] <= 1,
                'Box confidence below saved floor or invalid')


def load_round(name, path, ids, index, remaining, task):
    manifest = read(path / 'prediction_manifest.json')
    require(manifest['state'] == 'complete' and manifest['errors'] == 0
            and manifest['completed_frames'] == manifest['expected_frames'], 'Prediction not complete')
    expected = set(index) - ids
    require(manifest['completed_frames'] == len(expected), 'Round coverage count mismatch')
    filenames = {p.name for p in (path / 'predictions').glob('*.json')}
    require(filenames == {slug(fid) + '.json' for fid in expected}, 'Missing/extra prediction receipts')
    binding = manifest['binding']
    for key in ('protocol_sha256', 'source_export_manifest_sha256', 'source_frame_index_sha256'):
        require(binding[key] == task[key], f'Round source mismatch: {key}')
    threshold_path = path / 'confidence_threshold.json'
    threshold = read(threshold_path)
    completion = read(path / 'training/completed.json')
    require(digest(path / 'training/best.pt') == completion['best_checkpoint_sha256']
            == manifest['checkpoint_sha256'] == binding['checkpoint_sha256']
            == threshold['checkpoint_sha256'], 'Round checkpoint mismatch')
    require(digest(path / 'training/run.json') == completion['run_config_sha256'], 'Run config changed')
    require(digest(threshold_path) == binding['threshold_sha256'] == manifest['threshold_sha256'],
            'Round threshold mismatch')
    require(digest(path / 'manual_partition.json') == binding['manual_partition_sha256'],
            'Round partition changed after prediction')
    require(threshold['test_accessed'] is False, 'Threshold accessed test labels')
    floor = float(threshold['selected_confidence'])
    receipt_digest = hashlib.sha256()
    rows = {}
    for fid in sorted(remaining):
        receipt = path / 'predictions' / (slug(fid) + '.json')
        raw = receipt.read_bytes()
        row = json.loads(raw)
        validate_receipt(row, remaining[fid], binding, floor)
        receipt_digest.update(fid.encode() + b'\0' + hashlib.sha256(raw).digest())
        rows[fid] = row
    provenance = {'name': name, 'output': str(path), 'manual_frames': len(ids),
                  'checkpoint_sha256': manifest['checkpoint_sha256'],
                  'prediction_manifest_sha256': digest(path / 'prediction_manifest.json'),
                  'threshold_sha256': binding['threshold_sha256'], 'confidence_floor': floor,
                  'cohort_receipts_sha256': receipt_digest.hexdigest(),
                  'cohort_frames': len(rows), 'completed_epochs': completion['completed_epochs']}
    return rows, provenance


def iou_matrix(a, b):
    a, b = np.asarray(a, dtype=float).reshape(-1, 4), np.asarray(b, dtype=float).reshape(-1, 4)
    extent = np.maximum(0, np.minimum(a[:, None, 2:], b[None, :, 2:])
                        - np.maximum(a[:, None, :2], b[None, :, :2]))
    overlap = extent.prod(axis=2)
    area_a = (a[:, 2:] - a[:, :2]).prod(axis=1)
    area_b = (b[:, 2:] - b[:, :2]).prod(axis=1)
    return overlap / np.maximum(area_a[:, None] + area_b[None, :] - overlap, 1e-12)


def match_ious(ious, threshold=0.5):
    if not ious.size:
        return []
    # One additional valid match outweighs all possible changes in total IoU.
    eligible = ious >= threshold
    rewards = eligible * (min(ious.shape) + 1 + ious)
    rows, cols = linear_sum_assignment(rewards, maximize=True)
    return [(int(a), int(b), float(ious[a, b])) for a, b in zip(rows, cols) if eligible[a, b]]


def compare_frame(old, new, width, height, confidence=None):
    def chosen(boxes):
        return [b for b in boxes if confidence is None or b['score'] >= confidence]
    a, b = chosen(old), chosen(new)
    pairs = match_ious(iou_matrix([v['xyxy'] for v in a], [v['xyxy'] for v in b]))
    ious, edges, centres, scores = [], [], [], []
    for ai, bi, overlap in pairs:
        aa, bb = np.array(a[ai]['xyxy']), np.array(b[bi]['xyxy'])
        ious.append(overlap)
        edges.append(float(np.abs(aa - bb).max()))
        centres.append(float(np.linalg.norm((aa[:2] + aa[2:] - bb[:2] - bb[2:]) / 2)
                             / np.hypot(width, height)))
        scores.append(abs(a[ai]['score'] - b[bi]['score']))
    edge_fraction = [edge / min(width, height) for edge in edges]
    added, deleted = len(b) - len(pairs), len(a) - len(pairs)
    geometry = sum(i < METHOD['stable_iou'] or e > METHOD['max_edge_shift_short_side']
                   for i, e in zip(ious, edge_fraction))
    geometry90 = sum(i < METHOD['sensitivity_stable_iou'] or e > METHOD['max_edge_shift_short_side']
                     for i, e in zip(ious, edge_fraction))
    return {'old_boxes': len(a), 'new_boxes': len(b), 'matched': len(pairs),
            'added': added, 'deleted': deleted, 'both_empty': int(not a and not b),
            'nonempty': int(bool(a or b)), 'presence_changed': int(bool(a) != bool(b)),
            'count_changed': int(len(a) != len(b)), 'unmatched_changed': int(bool(added or deleted)),
            'geometry_changed_boxes': geometry, 'geometry_changed_frames': int(geometry > 0),
            'changed': int(bool(added or deleted or geometry)),
            'changed_iou90': int(bool(added or deleted or geometry90)),
            'ious': ious, 'edge_shift_pixels': edges, 'edge_shift_short_side': edge_fraction,
            'centre_shift_diagonal': centres, 'score_difference': scores}


def ratio(numerator, denominator):
    return numerator / denominator if denominator else None


def distribution(values):
    if not values:
        return {'n': 0, 'mean': None, 'p05': None, 'median': None, 'p95': None}
    return {'n': len(values), 'mean': float(np.mean(values)),
            'p05': float(np.quantile(values, .05)), 'median': float(np.median(values)),
            'p95': float(np.quantile(values, .95))}


def aggregate(rows, bootstrap=False):
    totals = {key: sum(row[key] for row in rows) for key in
              ('old_boxes', 'new_boxes', 'matched', 'added', 'deleted', 'both_empty',
               'nonempty', 'presence_changed', 'count_changed', 'unmatched_changed',
               'geometry_changed_boxes', 'geometry_changed_frames', 'changed', 'changed_iou90')}
    result = {'frames': len(rows), 'groups': len({row['group_id'] for row in rows}), **totals,
              'changed_frame_rate': ratio(totals['changed'], len(rows)),
              'changed_nonempty_frame_rate': ratio(totals['changed'], totals['nonempty']),
              'changed_frame_rate_iou90': ratio(totals['changed_iou90'], len(rows)),
              'box_set_jaccard': ratio(totals['matched'], totals['old_boxes'] + totals['new_boxes'] - totals['matched'])}
    for key in ('ious', 'edge_shift_pixels', 'edge_shift_short_side', 'centre_shift_diagonal', 'score_difference'):
        result[key] = distribution([value for row in rows for value in row[key]])
    if bootstrap:
        groups = defaultdict(list)
        for row in rows:
            groups[row['group_id']].append(row)
        if len(groups) < 2:
            result['group_bootstrap_95ci'] = {'available': False, 'reason': 'fewer than two groups'}
        else:
            arrays = np.asarray([[len(items), sum(v['changed'] for v in items), sum(v['nonempty'] for v in items)]
                                 for _, items in sorted(groups.items())], dtype=float)
            rng = np.random.default_rng(42)
            weights = rng.multinomial(len(groups), np.full(len(groups), 1 / len(groups)), size=2000)
            sums = weights @ arrays
            rates = sums[:, 1] / sums[:, 0]
            active = sums[sums[:, 2] > 0, 1] / sums[sums[:, 2] > 0, 2]
            result['group_bootstrap_95ci'] = {
                'available': True, 'replicates': 2000, 'seed': 42,
                'changed_frame_rate': np.quantile(rates, [.025, .975]).tolist(),
                'changed_nonempty_frame_rate': np.quantile(active, [.025, .975]).tolist() if len(active) else None}
    return result


def pair_result(left, right, remaining, confidence):
    rows = []
    for fid, source in sorted(remaining.items()):
        row = compare_frame(left[fid]['boxes_xyxy_score'], right[fid]['boxes_xyxy_score'],
                            *source['size'], confidence)
        row.update(frame_id=fid, group_id=source['group_id'], domain=source['domain'], split=source['split'])
        rows.append(row)
    result = {'overall': aggregate(rows, bootstrap=True)}
    for key in ('split', 'domain'):
        values = defaultdict(list)
        for row in rows:
            values[row[key]].append(row)
        result['by_' + key] = {name: aggregate(items, bootstrap=True) for name, items in sorted(values.items())}
    return result, rows


def judgement(pairs, complete):
    if not complete:
        return {'state': 'pending_third_round', 'stable': None,
                'explanation': 'Only the first pair is available; three-round convergence cannot yet be assessed.'}
    adjacent = [pair for pair in pairs if pair['adjacent']]
    passing = []
    for pair in adjacent:
        metrics = pair['common_confidence']['overall']
        ci = metrics['group_bootstrap_95ci']
        passing.append(metrics['changed_frame_rate'] < .01
                       and metrics['changed_nonempty_frame_rate'] is not None
                       and metrics['changed_nonempty_frame_rate'] < .01
                       and ci['available'] and ci['changed_frame_rate'][1] < .01
                       and ci['changed_nonempty_frame_rate'] is not None
                       and ci['changed_nonempty_frame_rate'][1] < .01)
    stable = bool(passing) and all(passing)
    return {'state': 'machine_proposals_stable' if stable else 'machine_proposals_not_converged',
            'stable': stable, 'correctness_confirmed': False,
            'operational_rule': METHOD['operational_convergence']}


def percent(value):
    return '不可计算' if value is None else f'{value:.2%}'


def report_markdown(result):
    lines = ['# 未人工检查候选标注的三轮稳定性比较', '',
             f'状态：**{"完整三轮比较" if result["state"] == "complete" else "仅前两轮初步比较，第三轮尚未完成"}**。', '',
             f'固定比较 {result["cohort"]["remaining_frames"]:,} 帧，排除累计 '
             f'{result["cohort"]["excluded_manual_frames"]:,} 张人工检查帧（含人工验证帧）。'
             '所有轮次均未以这些帧的人工标签训练或校准；原机器标签和独立参考框未参与评分。', '',
             '比较的是模型建议的一致程度，不能确认漏检、共同误检或共同错误框。'
             '三轮训练数据量及第三轮实际 batch 不同，变化不能归因于单一因素。', '',
             '## 固定比较规则', '',
             '以 IoU≥0.50 做一对一匹配，优先最多匹配，再最大化 IoU。新增/消失框、'
             '匹配 IoU<0.95 或任一边界移动超过原生图短边2%，均为实质变化。'
             '另报告 IoU=0.90 的敏感性统计。空框与空框单独计数，不当作正确负例。', '',
             f'共同置信度阈值为 **{result["common_confidence"]:.2f}**（各轮保存阈值的最大值），'
             '同时保留各自交付阈值的比较。旧轮阈值以下候选无法从保存文件恢复，未臆造。', '',
             '95%区间按完整采集组重采样2,000次、seed42，统计帧加权变化率。'
             '本轮预先登记的操作性收敛标准是相邻两次比较的全帧与非空帧变化率及其区间上界均低于1%；'
             '这是候选一致性标准，独立于原49帧人工/代理审计停止条件。', '',
             '## 共同阈值下的差异', '',
             '| 模型对 | 实质变化帧 | 非空帧变化率 | 框数量改变帧 | 新增/消失框 | 匹配框平均IoU | 双方空框帧 |',
             '|---|---:|---:|---:|---:|---:|---:|']
    for pair in result['pairs']:
        m = pair['common_confidence']['overall']
        mean = '—' if m['ious']['mean'] is None else f'{m["ious"]["mean"]:.4f}'
        lines.append(f'| {pair["from"]} → {pair["to"]} | {m["changed"]}/{m["frames"]} '
                     f'({percent(m["changed_frame_rate"])}) | {percent(m["changed_nonempty_frame_rate"])} '
                     f'| {m["count_changed"]} | {m["added"]}/{m["deleted"]} | {mean} | {m["both_empty"]} |')
    lines += ['', '| 模型对 | 实质变化率95%组级区间 | IoU=0.90规则变化率 | 匹配框最大边界偏移均值/p95（像素） |',
              '|---|---:|---:|---:|']
    for pair in result['pairs']:
        metrics = pair['common_confidence']['overall']
        ci = metrics['group_bootstrap_95ci']
        interval = ('—' if not ci['available'] else
                    '–'.join(percent(v) for v in ci['changed_frame_rate']))
        edges = metrics['edge_shift_pixels']
        edge_text = '—' if edges['mean'] is None else f'{edges["mean"]:.2f}/{edges["p95"]:.2f}'
        lines.append(f'| {pair["from"]} → {pair["to"]} | {interval} '
                     f'| {percent(metrics["changed_frame_rate_iou90"])} | {edge_text} |')
    lines += ['', '## 判断', '']
    decision = result['judgement']
    if result['state'] != 'complete':
        lines.append('第三轮训练、全量预测及修正包审计尚未完成，不能给出三轮稳定结论。'
                     '当前结果可识别第一至第二轮的差异，但不能说明最近一轮已经收敛。')
    elif decision['stable']:
        lines.append('三轮在本次操作性标准下达到候选稳定，但不表示未检查标注正确；仍需人工检查。')
    else:
        lines.append('三轮未达到本次操作性收敛标准，剩余建议仍需人工检查和修正；不能自动接受。')
    if len(result['pairs']) == 3:
        a, b = [pair['common_confidence']['overall']['changed_frame_rate']
                for pair in result['pairs'] if pair['adjacent']]
        trend = '降低' if b < a else '增加或持平'
        lines.append(f'相邻轮次变化率由 {percent(a)} 变为 {percent(b)}，差异{trend}。'
                     '单次下降不单独证明稳定；完整区间、配置域与划分统计见JSON。')
    lines += ['', '## 人工检查入口', '',
              '`review_priority.csv` 为固定剩余范围的逐帧排序：优先最新相邻轮次增删框，'
              '其次边界变化；同时保留早期差异、三轮全空标记、原生文件名和各轮框数。'
              '全空帧也必须检查是否漏标。排序不会自动修改AnyLabeling标签。', '',
              '全量JSON包含各划分/配置域统计、组级区间、框IoU、像素/归一化边界偏移、'
              '置信度变化和模型/阈值/标签/清单/逐帧建议哈希。', '',
              '本比较没有使用val/test真值，没有报告AP或测试性能，原冻结研究参考保持原样。', '']
    return '\n'.join(lines)


def analysis(args, rounds, index, remaining, task):
    loaded, provenance = [], []
    for name, path, ids in rounds:
        rows, source = load_round(name, path, ids, index, remaining, task)
        loaded.append(rows)
        provenance.append(source)
    inputs_path = args.output / 'prediction_inputs.json'
    if inputs_path.exists():
        require(read(inputs_path) == provenance, 'Saved prediction inputs changed; use a new analysis version')
    else:
        write(inputs_path, provenance)
    common = max(p['confidence_floor'] for p in provenance)
    pairs, frame_pairs = [], []
    for ai, bi in itertools.combinations(range(len(rounds)), 2):
        shared, frame_rows = pair_result(loaded[ai], loaded[bi], remaining, common)
        native, _ = pair_result(loaded[ai], loaded[bi], remaining, None)
        pairs.append({'from': rounds[ai][0], 'to': rounds[bi][0], 'adjacent': bi == ai + 1,
                      'native_confidence': native, 'common_confidence': shared})
        frame_pairs.append({row['frame_id']: row for row in frame_rows})
    complete = len(rounds) == args.expected_rounds
    result = {'state': 'complete' if complete else 'partial',
              'created_at': datetime.now(ZoneInfo('Asia/Shanghai')).isoformat(),
              'cohort': task, 'rounds': provenance, 'common_confidence': common, 'pairs': pairs,
              'judgement': judgement(pairs, complete), 'test_ground_truth_accessed': False}
    if complete:
        result['three_round_consensus'] = {
            'all_empty_frames': sum(all(not r[fid]['boxes_xyxy_score'] or
                                        not any(b['score'] >= common for b in r[fid]['boxes_xyxy_score'])
                                        for r in loaded) for fid in remaining),
            'no_substantive_pairwise_change_frames': sum(all(not p[fid]['changed'] for p in frame_pairs)
                                                        for fid in remaining),
            'correctness_confirmed': False}
    write(args.output / 'comparison.json', result)
    (args.output / 'report_zh.md').write_text(report_markdown(result))
    adjacent_indices = [i for i, p in enumerate(pairs) if p['adjacent']]
    current_pair = frame_pairs[adjacent_indices[-1]]
    priority = []
    for fid, source in remaining.items():
        current = current_pair[fid]
        priority.append({'frame_id': fid, 'split': source['split'], 'domain': source['domain'],
                         'group_id': source['group_id'], 'image': source['image'],
                         'annotation': source['annotation'], 'latest_added': current['added'],
                         'latest_deleted': current['deleted'], 'latest_geometry_changed': current['geometry_changed_boxes'],
                         'latest_substantive_change': current['changed'],
                         'any_pair_substantive_change': int(any(p[fid]['changed'] for p in frame_pairs)),
                         'all_rounds_empty': int(all(not any(b['score'] >= common for b in r[fid]['boxes_xyxy_score'])
                                                     for r in loaded)),
                         'round_box_counts': '|'.join(str(sum(b['score'] >= common for b in r[fid]['boxes_xyxy_score']))
                                                     for r in loaded),
                         'min_latest_matched_iou': min(current['ious']) if current['ious'] else ''})
    priority.sort(key=lambda r: (-(r['latest_added'] + r['latest_deleted']),
                                 -r['latest_substantive_change'], -r['latest_geometry_changed'],
                                 -r['any_pair_substantive_change'], r['frame_id']))
    for rank, row in enumerate(priority, 1):
        row['priority_rank'] = rank
    with (args.output / 'review_priority.csv').open('w', newline='', encoding='utf-8-sig') as stream:
        writer = csv.DictWriter(stream, fieldnames=['priority_rank'] + [k for k in priority[0] if k != 'priority_rank'])
        writer.writeheader()
        writer.writerows(priority)
    make_plot(result, args.output)
    write(args.output / 'analysis_artifacts.json', {name: digest(args.output / name) for name in
          ('comparison.json', 'report_zh.md', 'review_priority.csv', 'proposal_change_rates.png')})
    return result


def make_plot(result, output):
    import matplotlib
    matplotlib.use('Agg')
    import matplotlib.pyplot as plt
    labels, native, common = [], [], []
    for pair in result['pairs']:
        labels.append(pair['from'] + '\n→ ' + pair['to'])
        native.append(pair['native_confidence']['overall']['changed_frame_rate'] * 100)
        common.append(pair['common_confidence']['overall']['changed_frame_rate'] * 100)
    x = np.arange(len(labels))
    fig, ax = plt.subplots(figsize=(8, 4.5))
    ax.bar(x - .18, native, .36, label='Delivered confidence thresholds')
    ax.bar(x + .18, common, .36, label=f'Common threshold {result["common_confidence"]:.2f}')
    ax.axhline(1, color='red', linestyle='--', label='Operational 1% criterion')
    ax.set_xticks(x, labels)
    ax.set_ylabel('Frames with substantive proposal changes (%)')
    ax.set_title('Same unreviewed cohort; proposal stability, not accuracy')
    ax.legend(fontsize=8)
    fig.tight_layout()
    fig.savefig(output / 'proposal_change_rates.png', dpi=160)
    plt.close(fig)


def pid_alive(pid):
    try:
        os.kill(pid, 0)
        return Path(f'/proc/{pid}/stat').read_text().split(') ', 1)[1][0] != 'Z'
    except (FileNotFoundError, ProcessLookupError):
        return False


def final_delivery(args, result, remaining):
    latest = Path(args.round[-1].partition('=')[2]).resolve()
    audit = read(latest / 'package_audit.json')
    archive = latest / f'human_correction_remaining_{len(remaining)}_v1.zip'
    require(result['state'] == 'complete', 'Three-round comparison incomplete')
    require(audit['state'] == 'passed' and audit['zip_crc'] == 'passed'
            and audit['frames'] == len(remaining) and audit['manual_overlap'] == 0,
            'Correction package failed audit or has wrong coverage')
    require(audit['split_counts'] == dict(Counter(row['split'] for row in remaining.values())),
            'Correction package split coverage changed')
    require(digest(archive) == audit['zip_sha256'], 'Correction archive changed')
    require(audit.get('validation_test_labels_scored') is False, 'Package used independent test labels')
    delivery = {'state': 'complete', 'remaining_frames': len(remaining),
                'excluded_manual_frames': result['cohort']['excluded_manual_frames'],
                'correction_zip': str(archive), 'correction_zip_sha256': audit['zip_sha256'],
                'stability_report': str((args.output / 'report_zh.md').resolve()),
                'priority_csv': str((args.output / 'review_priority.csv').resolve()),
                'comparison_sha256': digest(args.output / 'comparison.json'),
                'stability_judgement': result['judgement'],
                'analysis_does_not_modify_labels': True, 'test_ground_truth_accessed': False}
    write(args.output / 'delivery_manifest.json', delivery)
    project = Path(__file__).resolve().parent.parent
    marker = '<!-- manual-proposal-stability:' + args.output.name + ' -->'
    text = (f'\n\n{marker}\n## {datetime.now(ZoneInfo("Asia/Shanghai")):%Y-%m-%d}：剩余修正包及三轮建议稳定性\n\n'
            f'已排除累计{delivery["excluded_manual_frames"]}人工检查帧，剩余{len(remaining)}帧修正包全量审计通过。'
            f'ZIP：`{archive.relative_to(project)}`；SHA-256 `{audit["zip_sha256"]}`。'
            f'固定同一未检查范围完成三轮建议差异比较，结论：'
            f'{"达到操作性候选稳定标准" if result["judgement"]["stable"] else "未达到操作性候选收敛标准"}。'
            '稳定性不代表正确，仍需人工检查。'
            f'报告：`{(args.output / "report_zh.md").relative_to(project)}`；优先检查CSV与报告同目录。\n')
    for filename in ('docs/training_log.md', 'docs/change_log.md', 'docs/session_summary.md', 'README.md'):
        path = project / filename
        current = path.read_text()
        if marker not in current:
            path.write_text(current + text)
    return delivery


def main():
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--round', action='append', required=True, help='NAME=OUTPUT, oldest first')
    parser.add_argument('--manual-output', type=Path, required=True)
    parser.add_argument('--source-export', type=Path, default=Path('outputs/anylabeling/pallet_v5_20260930'))
    parser.add_argument('--protocol', type=Path, default=Path('outputs/protocol_v5'))
    parser.add_argument('--output', type=Path, required=True)
    parser.add_argument('--expected-rounds', type=int, default=3)
    parser.add_argument('--wait', action='store_true', help='Wait for all prediction and correction-package audits')
    parser.add_argument('--workflow-pid', type=int, help='Exit resumably if the upstream workflow stops')
    args = parser.parse_args()
    require(args.expected_rounds == 3 and len(args.round) in (2, 3), 'This task compares two or three rounds')
    require(not args.wait or len(args.round) == 3, '--wait requires all three rounds')
    rounds, index, remaining, task = prepare(args)
    if args.wait:
        while True:
            pending = []
            for name, path, _ in rounds:
                manifest = path / 'prediction_manifest.json'
                if not manifest.exists() or read(manifest).get('state') != 'complete':
                    pending.append(name)
            latest = rounds[-1][1]
            if not pending and (latest / 'package_audit.json').exists():
                break
            state = {'state': 'waiting_for_upstream', 'pending_rounds': pending,
                     'waiting_for_package_audit': not (latest / 'package_audit.json').exists(),
                     'remaining_frames': len(remaining), 'excluded_manual_frames': task['excluded_manual_frames'],
                     'updated_at': datetime.now(ZoneInfo('Asia/Shanghai')).isoformat()}
            if args.workflow_pid and not pid_alive(args.workflow_pid):
                state.update(state='failed_resumable', reason='Upstream stopped before audited package')
                write(args.output / 'status.json', state)
                raise SystemExit(state['reason'])
            write(args.output / 'status.json', state)
            time.sleep(30)
        # Revalidate frozen inputs before analysis after a potentially long wait.
        rounds, index, remaining, task = prepare(args)
    write(args.output / 'status.json', {'state': 'analyzing', 'remaining_frames': len(remaining)})
    try:
        result = analysis(args, rounds, index, remaining, task)
        if args.wait:
            final_delivery(args, result, remaining)
        write(args.output / 'status.json', {'state': result['state'], 'judgement': result['judgement'],
              'updated_at': datetime.now(ZoneInfo('Asia/Shanghai')).isoformat()})
        print(json.dumps({'state': result['state'], 'judgement': result['judgement'],
                          'report': str(args.output / 'report_zh.md')}, ensure_ascii=False), flush=True)
    except Exception as error:
        write(args.output / 'status.json', {'state': 'failed_resumable', 'error': str(error)})
        raise


if __name__ == '__main__':
    main()
