"""Balanced, diverse, partially annotated AnyLabeling fork-face seed sets.

Cluster IDs are sampling attributes, not supervised segmentation classes. Native
frames are unique across clusters; other parent boxes remain explicitly ignored.
"""
from __future__ import annotations

import argparse
from collections import Counter, defaultdict
import copy
import csv
from datetime import datetime, timedelta, timezone
import hashlib
import html
import io
import importlib.metadata
import json
import math
from pathlib import Path
import tempfile
import zipfile

import numpy as np
from PIL import Image, ImageDraw
from scipy.sparse import csr_matrix
from scipy.sparse.csgraph import maximum_bipartite_matching

from pallet.fork_face_anylabeling import (
    LABEL, digest, encoded, load_upstream, protected_write, read_checked, safe_path,
)
from pallet.fork_face_simplify import check_label_save, load_label_file


DEFAULT_CLUSTERING = Path('outputs/pallet_target_clustering_v1/analysis/run_006')
DEFAULT_SOURCE = Path('outputs/pallet_fork_face_anylabeling_enclosure_v2/delivery')
DEFAULT_OUTPUT = Path('outputs/pallet_cluster_annotation_seed_v1')
SPLITS = ('train', 'val', 'test')
COLORS = [(38, 190, 142), (242, 133, 61), (98, 149, 244), (230, 106, 175),
          (175, 144, 241), (217, 184, 44), (60, 191, 209), (218, 92, 87)]


def jsonl(path):
    with Path(path).open() as stream:
        return [json.loads(line) for line in stream if line.strip()]


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


def log(stage, **values):
    print(json.dumps({'stage': stage, **values}, ensure_ascii=False), flush=True)


def native_box(bbox, size):
    height, width = size
    values = [float(bbox[k]) for k in ('x', 'y', 'width', 'height')]
    if not all(math.isfinite(x) for x in values) or min(values[2:]) <= 0:
        raise ValueError('Invalid floating parent box')
    x, y, w, h = values
    result = [max(0, math.floor(x)), max(0, math.floor(y)),
              min(width, math.ceil(x+w)), min(height, math.ceil(y+h))]
    if result[2] <= result[0] or result[3] <= result[1]:
        raise ValueError('Parent box outside native frame')
    return result


def ignore_regions(parents, selected_id, size):
    mask = np.zeros(size, bool)
    ignored = []
    for parent in parents:
        if parent['target_id'] == selected_id:
            continue
        region = native_box(parent['bbox'], size)
        x0, y0, x1, y1 = region
        mask[y0:y1, x0:x1] = True
        ignored.append({**copy.deepcopy(parent), 'integer_bbox': region,
                        'annotation_status': 'not_selected_ignore'})
    return mask, ignored


def split_quotas(rows, per_cluster):
    result = {}
    for cluster in sorted({r['appearance_cluster'] for r in rows if r['appearance_cluster'] >= 0}):
        remaining = per_cluster
        for split in SPLITS:
            frames = {r['frame_id'] for r in rows
                      if r['appearance_cluster'] == cluster and r['split'] == split}
            count = min(remaining, len(frames))
            if count:
                result[(cluster, split)] = count
            remaining -= count
        if remaining:
            raise ValueError(f'A{cluster:02d}: insufficient distinct frames ({per_cluster-remaining}/{per_cluster})')
    return result


def select_targets(rows, features, per_cluster=10, seed=42, progress=False):
    """Group/domain balancing and farthest-point sampling with matching lookahead."""
    features = np.asarray(features, dtype=np.float64)
    if features.ndim != 2 or len(features) != len(rows) or not np.isfinite(features).all():
        raise ValueError('Feature matrix and target identities do not align')
    if per_cluster < 1 or len({r['target_id'] for r in rows}) != len(rows):
        raise ValueError('Invalid sample count or duplicate target identity')
    pools = defaultdict(list)
    for i, row in enumerate(rows):
        if row['appearance_cluster'] >= 0:
            if row['split'] not in SPLITS:
                raise ValueError('Unknown original split')
            pools[(row['appearance_cluster'], row['split'])].append(i)
    quotas = split_quotas(rows, per_cluster)
    remaining = dict(quotas)
    frame_names = sorted({r['frame_id'] for r in rows if r['appearance_cluster'] >= 0})
    frame_index = {name: i for i, name in enumerate(frame_names)}
    pool_frames = {key: sorted({frame_index[rows[i]['frame_id']] for i in indices})
                   for key, indices in pools.items()}
    used = set()

    def feasible():
        rr, cc, slot = [], [], 0
        for key, number in sorted(remaining.items()):
            if not number:
                continue
            available = [i for i in pool_frames[key] if i not in used]
            if len(available) < number:
                return False
            for _ in range(number):
                rr.extend([slot]*len(available)); cc.extend(available); slot += 1
        if slot == 0:
            return True
        graph = csr_matrix((np.ones(len(rr), dtype=np.int8), (rr, cc)),
                           shape=(slot, len(frame_names)))
        return bool((maximum_bipartite_matching(graph, perm_type='column') >= 0).all())

    if not feasible():
        raise ValueError('Split quotas cannot be satisfied with globally unique native frames')
    selected, coverage = [], []
    for cluster in sorted({key[0] for key in quotas}):
        all_indices = [i for key, indices in pools.items() if key[0] == cluster for i in indices]
        center = np.median(features[all_indices], axis=0)
        chosen, group_counts, domain_counts = [], Counter(), Counter()
        for split in SPLITS:
            key = (cluster, split)
            for _ in range(quotas.get(key, 0)):
                candidates = [i for i in pools[key] if frame_index[rows[i]['frame_id']] not in used]
                distances = (np.linalg.norm(features[candidates]-center, axis=1) if not chosen else
                             np.min(np.linalg.norm(features[candidates, None]-features[chosen][None], axis=2), axis=1))
                rankings = []
                for i, distance in zip(candidates, distances):
                    tie = hashlib.sha256(f'{seed}\0{rows[i]["target_id"]}'.encode()).hexdigest()
                    rankings.append(((group_counts[rows[i]['group_id']], domain_counts[rows[i]['domain']],
                                      float(distance) if not chosen else -float(distance), tie), i, float(distance)))
                accepted = None
                for _, i, distance in sorted(rankings):
                    frame = frame_index[rows[i]['frame_id']]
                    used.add(frame); remaining[key] -= 1
                    if feasible():
                        accepted = (i, distance)
                        break
                    used.remove(frame); remaining[key] += 1
                if accepted is None:
                    raise ValueError(f'A{cluster:02d}: no feasible diverse candidate remains')
                i, distance = accepted
                row = copy.deepcopy(rows[i])
                row.update({'appearance_class': f'A{cluster:02d}', 'selection_order': len(chosen)+1,
                            'selection_distance': distance,
                            'selection_distance_kind': 'cluster_center' if not chosen else 'nearest_selected',
                            'seed': seed, 'segmentation_label': LABEL,
                            'human_reviewed': False, 'mask_human_reviewed': False,
                            'proposal_only': True, 'segmentation_training_eligible': False})
                selected.append(row); chosen.append(i)
                group_counts[row['group_id']] += 1; domain_counts[row['domain']] += 1
        nearest = np.min(np.linalg.norm(features[all_indices, None]-features[chosen][None], axis=2), axis=1)
        pairwise = np.linalg.norm(features[chosen, None]-features[chosen][None], axis=2)
        upper = pairwise[np.triu_indices(len(chosen), 1)]
        coverage.append({'appearance_class': f'A{cluster:02d}', 'available_targets': len(all_indices),
                         'selected_targets': len(chosen), 'available_groups': len({rows[i]['group_id'] for i in all_indices}),
                         'selected_groups': len(group_counts), 'selected_domains': dict(domain_counts),
                         'source_splits': dict(Counter(rows[i]['split'] for i in chosen)),
                         'nearest_selected_feature_distance_p50_p90_max': [float(x) for x in np.quantile(nearest, [.5, .9, 1])],
                         'selected_pair_distance_min_median': [float(np.min(upper)), float(np.median(upper))] if len(upper) else None})
        if progress:
            log('select', appearance_class=f'A{cluster:02d}', targets=len(chosen), groups=len(group_counts))
    return selected, coverage, {f'A{c:02d}/{s}': n for (c, s), n in sorted(quotas.items())}


def load_context(args):
    clustering, source = args.clustering.resolve(), args.source.resolve()
    output = args.output.resolve()
    if any(output.is_relative_to(p) or p.is_relative_to(output) for p in (clustering, source)):
        raise ValueError('Output must be separate from frozen input directories')
    checksum_lines = (clustering/'checksums.sha256').read_text().splitlines()
    cluster_hashes = {line.split('  ', 1)[1]: line.split('  ', 1)[0] for line in checksum_lines}
    cluster_files = ['targets.jsonl', 'features.npz', 'clusters.json']
    for name in cluster_files:
        read_checked(clustering, name, cluster_hashes)
    rows = jsonl(clustering/'targets.jsonl')
    descriptions = json_value(clustering/'clusters.json')['appearance']
    expected = {c['cluster_id'] for c in descriptions}
    if {r['appearance_cluster'] for r in rows if r['appearance_cluster'] >= 0} != expected:
        raise ValueError('Cluster description and target assignments disagree')
    with np.load(clustering/'features.npz', allow_pickle=False) as cache:
        indices = cache['appearance_indices']
        if len(indices) != len(rows) or set(indices.tolist()) != set(range(len(rows))):
            raise ValueError('Appearance cache does not cover all source targets')
        features = np.empty_like(cache['appearance_features'])
        features[indices] = cache['appearance_features']
    assets_path = source/'verified_assets.json'
    frozen = json_value(assets_path)
    source_hashes = frozen['files']
    receipt_path = source.parent/'delivery_manifest.json'
    receipt = json_value(receipt_path) if receipt_path.exists() else None
    if receipt and receipt['validation']['verified_assets_sha256'] != digest(assets_path):
        raise ValueError('Frozen segmentation asset registry changed')
    for name in ['manifest.json', 'frames.jsonl', 'targets.jsonl', 'source/config.json',
                 'source/anylabeling_label_file.py', 'source/anylabeling_shape.py']:
        read_checked(source, name, source_hashes)
    manifest = json_value(source/'manifest.json')
    config = manifest['binding']['config']
    frames = jsonl(source/'frames.jsonl')
    frame_map = {f['frame_id']: f for f in frames}
    if len(frame_map) != len(frames) or any(r['frame_id'] not in frame_map for r in rows):
        raise ValueError('Missing or duplicate segmentation frame identity')
    shape_file = source/'source/anylabeling_shape.py'
    label_file = source/'source/anylabeling_label_file.py'
    upstream = load_upstream(shape_file, config['upstream_shape_sha256'])
    label_class = load_label_file(label_file, config['upstream_label_sha256'])
    inputs = {str(clustering/name): cluster_hashes[name] for name in cluster_files}
    inputs[str(clustering/'checksums.sha256')] = digest(clustering/'checksums.sha256')
    inputs[str(assets_path)] = digest(assets_path)
    for name in ['manifest.json', 'frames.jsonl', 'targets.jsonl', 'source/config.json',
                 'source/anylabeling_label_file.py', 'source/anylabeling_shape.py']:
        inputs[str(source/name)] = source_hashes[name]
    if receipt:
        inputs[str(receipt_path)] = digest(receipt_path)
    cluster_manifest = clustering.parent.parent/'run_manifest.json'
    formal = json_value(cluster_manifest) if cluster_manifest.exists() else {}
    if formal:
        inputs[str(cluster_manifest)] = digest(cluster_manifest)
    bundled_font = Path(__file__).with_name('assets')/'AnnotationSeedSans.woff'
    font = args.font.resolve() if args.font else (bundled_font if bundled_font.exists() else clustering/'PalletReportSans.woff')
    if font.exists():
        inputs[str(font)] = digest(font)
    elif args.font:
        raise FileNotFoundError(font)
    bundled_license = Path(__file__).with_name('assets')/'FONT_LICENSE.txt'
    license_file = bundled_license if font == bundled_font else clustering/'FONT_LICENSE.txt'
    if license_file.exists():
        inputs[str(license_file)] = digest(license_file)
    code_files = [Path(__file__), Path(__file__).with_name('fork_face_anylabeling.py'),
                  Path(__file__).with_name('fork_face_simplify.py')]
    binding = {'kind': 'diverse_cluster_annotation_seed', 'version': 1,
               'clustering': str(clustering), 'segmentation_source': str(source),
               'per_cluster': args.per_cluster, 'seed': args.seed, 'cluster_ids': sorted(expected),
               'native_unique_frames': True, 'sampling': 'group_domain_balanced_farthest_point_with_matching',
               'source_split_priority': list(SPLITS), 'label': LABEL, 'view': 'faces',
               'inputs': inputs, 'code_sha256': {p.name: digest(p) for p in code_files},
               'dependencies': {name: importlib.metadata.version(name) for name in
                                ('numpy', 'scipy', 'pillow', 'markdown-it-py', 'shapely')}}
    binding['task_hash'] = hashlib.sha256(encoded(binding)).hexdigest()
    args.output.mkdir(parents=True, exist_ok=True)
    protected_write(args.output/'run_manifest.json', encoded(binding))
    return dict(args=args, clustering=clustering, source=source, output=args.output,
                delivery=args.output/'delivery', rows=rows, features=features, frames=frame_map,
                hashes=source_hashes, cluster_hashes=cluster_hashes, binding=binding,
                formal=formal, upstream=upstream, label_class=label_class, font=font,
                license_file=license_file, descriptions=descriptions)


def run_select(ctx):
    args, output = ctx['args'], ctx['output']
    selected, coverage, quotas = select_targets(ctx['rows'], ctx['features'], args.per_cluster, args.seed, True)
    protected_write(output/'selection.jsonl', b''.join(encoded(r) for r in selected))
    protected_write(output/'selection_summary.json', encoded({'coverage': coverage, 'quotas': quotas,
                    'targets': len(selected), 'unique_frames': len({r['frame_id'] for r in selected}),
                    'source_splits': dict(Counter(r['split'] for r in selected)),
                    'appearance_noise_excluded': True, 'negative_frames_excluded': True}))
    return selected


def png_bytes(mask):
    buffer = io.BytesIO()
    Image.fromarray(np.asarray(mask, dtype=np.uint8)*255).save(buffer, format='PNG')
    return buffer.getvalue()


def raster_groups(document, size, upstream):
    result = {}
    for shape in document['shapes']:
        points = np.asarray(shape['points'], dtype=float)
        group = shape['group_id']
        if (shape['label'] != LABEL or shape['shape_type'] != 'polygon' or not isinstance(group, int)
                or isinstance(group, bool) or group < 1 or points.ndim != 2 or points.shape[1] != 2
                or len(points) < 3 or not np.isfinite(points).all() or points.min() < 0
                or points[:, 0].max() >= size[1] or points[:, 1].max() >= size[0]):
            raise ValueError('Invalid native face polygon or group identity')
        pixels = upstream(size, points.tolist(), 'polygon')
        result.setdefault(group, np.zeros(size, bool))[:] |= pixels
    return result


def preview(image_bytes, document, row, ignored):
    image = Image.open(io.BytesIO(image_bytes)).convert('RGBA')
    layer = Image.new('RGBA', image.size)
    draw = ImageDraw.Draw(layer)
    for i, shape in enumerate(document['shapes']):
        color = COLORS[i % len(COLORS)]
        points = [tuple(p) for p in shape['points']]
        draw.polygon(points, fill=(*color, 65), outline=(*color, 255), width=1)
        draw.text(points[0], f'g{shape["group_id"]}', fill=(255, 255, 255, 255))
    for parent in ignored:
        x0, y0, x1, y1 = parent['integer_bbox']
        draw.rectangle((x0, y0, x1-1, y1-1), outline=(185, 185, 185, 255), width=1)
    region = native_box(row['bbox'], (image.height, image.width))
    draw.rectangle((region[0], region[1], region[2]-1, region[3]-1), outline=(255, 230, 50, 255), width=2)
    image = Image.alpha_composite(image, layer).convert('RGB')
    header = Image.new('RGB', (max(image.width, 280), image.height+24), '#142e39')
    header.paste(image, (0, 24))
    ImageDraw.Draw(header).text((7, 6), f'{row["appearance_class"]} / {row["split"]} / p{row["box_index"]+1} / {len(document["shapes"])} faces', fill='white')
    buffer = io.BytesIO(); header.save(buffer, format='JPEG', quality=92)
    return buffer.getvalue()


def export_target(ctx, row):
    delivery, source, hashes = ctx['delivery'], ctx['source'], ctx['hashes']
    frame = ctx['frames'][row['frame_id']]
    name, key = row['appearance_class'], frame['frame_key']
    record_path = ctx['output']/'records'/name/(key+'.json')
    if record_path.exists():
        record = json_value(record_path)
        if record['task_hash'] != ctx['binding']['task_hash'] or record['target_id'] != row['target_id']:
            raise ValueError('Completed target identity changed')
        for path, expected in record['files'].items():
            if digest(safe_path(delivery, path)) != expected:
                raise ValueError(f'Completed file changed; human edits are protected: {path}')
        for path, expected in record['source_files'].items():
            if digest(safe_path(source, path)) != expected:
                raise ValueError(f'Frozen source changed: {path}')
        return record
    source_json = frame['views']['faces']['annotation']
    source_image = frame['views']['faces']['image']
    original = json.loads(read_checked(source, source_json, hashes))
    image = read_checked(source, source_image, hashes)
    size = (frame['height'], frame['width'])
    with Image.open(io.BytesIO(image)) as native:
        if (native.height, native.width) != size:
            raise ValueError('Native PNG/frame dimensions disagree')
    meta = original['pallet_segmentation']
    if (meta['frame_id'] != row['frame_id'] or meta['frame_key'] != key or meta['original_split'] != row['split']
            or (original['imageHeight'], original['imageWidth']) != size):
        raise ValueError('Source frame identity, split or native dimensions disagree')
    parents = [p for p in meta['parents'] if p['target_id'] == row['target_id']]
    if len(parents) != 1 or parents[0]['bbox'] != row['bbox'] or parents[0]['pallet_group_id'] != row['box_index']+1:
        raise ValueError('Clustering and segmentation parent identity/box disagree')
    groups = [copy.deepcopy(g) for g in meta['groups'] if g['target_id'] == row['target_id']]
    ids = {g['group_id'] for g in groups}
    if len(ids) != len(groups):
        raise ValueError('Duplicate selected face identity')
    document = copy.deepcopy(original)
    document['shapes'] = [copy.deepcopy(s) for s in original['shapes'] if s['group_id'] in ids]
    for shape in document['shapes']:
        part = shape['pallet_mask_part']
        if part['pallet_group_id'] != row['box_index']+1 or part['face_id'] != shape['group_id']:
            raise ValueError('Source face and parent identity disagree')
        shape['flags'].update({'human_reviewed': False, 'mask_human_reviewed': False,
                               'proposal_only': True, 'segmentation_training_eligible': False})
        shape['pallet_mask_part'].update({'target_id': row['target_id'], 'appearance_class': name})
    pixels = raster_groups(document, size, ctx['upstream'])
    if set(pixels) != ids or any(not m.any() for m in pixels.values()):
        raise ValueError('Selected group is empty or has no source polygon')
    counts = np.zeros(size, np.int32)
    for mask in pixels.values():
        counts += mask
    ignore, ignored = ignore_regions(meta['parents'], row['target_id'], size)
    face_overlap, ignore_overlap = counts > 1, (counts > 0) & ignore
    prefix = f'{name}/images/{key}'
    ignore_path = f'ignore_masks/{name}/{key}.png'
    overlap_path = f'face_overlaps/{name}/{key}.png'
    ignore_overlap_path = f'selected_ignore_overlaps/{name}/{key}.png'
    files, source_files = {}, {source_json: hashes[source_json], source_image: hashes[source_image]}

    def write(relative, data):
        protected_write(safe_path(delivery, relative), data)
        files[relative] = hashlib.sha256(data).hexdigest()

    for group in groups:
        original_mask = group['mask']
        relative = f'reference_masks/{name}/{row["target_key"]}__face_{group["face_id"]:04d}.png'
        data = read_checked(source, original_mask, hashes)
        evidence = np.asarray(Image.open(io.BytesIO(data)))
        if evidence.shape != size or not np.isin(evidence, [0, 255]).all():
            raise ValueError('Original face mask does not use the native binary grid')
        if ((evidence > 0) & ~pixels[group['group_id']]).any():
            raise ValueError('Source enclosing polygon no longer covers its reference mask')
        source_files[original_mask] = hashes[original_mask]
        write(relative, data)
        group.update({'mask': relative, 'mask_sha256': hashlib.sha256(data).hexdigest(),
                      'appearance_class': name, 'human_reviewed': False, 'mask_human_reviewed': False,
                      'proposal_only': True, 'segmentation_training_eligible': False,
                      'overlap_pixels': int((pixels[group['group_id']] & face_overlap).sum()),
                      'ignore_overlap_pixels': int((pixels[group['group_id']] & ignore).sum()),
                      'enclosure_overlap_needs_review': bool((pixels[group['group_id']] & face_overlap).any())})
    reasons = sorted(set(row.get('review_reasons', [])) | set(parents[0].get('review_reasons', [])))
    if face_overlap.any(): reasons.append('selected_face_enclosures_overlap')
    if ignore_overlap.any(): reasons.append('selected_face_intersects_ignored_parent')
    if not groups: reasons.append('no_face_proposal_redraw_required')
    document['imagePath'] = key+'.png'
    document['imageData'] = None
    document['flags'].update({'human_reviewed': False, 'mask_human_reviewed': False,
         'proposal_only': True, 'unreviewed': True, 'confirmed_negative': False,
         'unresolved_positive': not bool(groups), 'redraw_required': not bool(groups),
         'partial_annotation': bool(ignored), 'enclosure_overlap': bool(face_overlap.any()),
         'ignore_overlap_needs_review': bool(ignore_overlap.any()), 'segmentation_training_eligible': False})
    document['checked'] = False
    selected_parent = copy.deepcopy(parents[0])
    selected_parent.update({'appearance_class': name, 'human_reviewed': False,
                            'mask_human_reviewed': False, 'segmentation_training_eligible': False})
    document['pallet_segmentation'].update({'schema_version': 4, 'view': 'faces', 'parents': [selected_parent],
         'groups': groups, 'original_split': row['split'], 'appearance_class': name,
         'annotation_scope': 'selected_parent_only', 'selected_target_ids': [row['target_id']],
         'ignored_parents': ignored, 'ignore_mask': ignore_path, 'ignore_mask_values': {'valid': 0, 'ignore': 255},
         'face_overlap_mask': overlap_path, 'selected_ignore_overlap_mask': ignore_overlap_path,
         'overlap_pixels': int(face_overlap.sum()), 'ignore_overlap_pixels': int(ignore_overlap.sum()),
         'unresolved_target_ids': [] if groups else [row['target_id']], 'task_hash': ctx['binding']['task_hash'],
         'cluster_source': str(ctx['clustering']), 'source_annotation': source_json,
         'seed_role': 'independent_segmentation_annotation_seed', 'source_split_is_provenance_only': True,
         'human_reviewed': False, 'mask_human_reviewed': False, 'proposal_only': True,
         'segmentation_training_eligible': False, 'review_reasons': reasons})
    document['text'] = (f'{name}; selected p{row["box_index"]+1}; edit each visible face; '
                        f'{len(ignored)} other parents ignored; {int(ignore_overlap.sum())} ignored overlap pixels')
    write(prefix+'.png', image); write(prefix+'.json', encoded(document))
    write(ignore_path, png_bytes(ignore)); write(overlap_path, png_bytes(face_overlap))
    write(ignore_overlap_path, png_bytes(ignore_overlap))
    preview_path = f'previews/{name}/{key}.jpg'
    write(preview_path, preview(image, document, row, ignored))
    face_previews = []
    for group in groups:
        single = {**document, 'shapes': [s for s in document['shapes'] if s['group_id'] == group['group_id']]}
        relative = f'previews/{name}/faces/{key}__face_{group["face_id"]:04d}.jpg'
        write(relative, preview(image, single, row, ignored))
        face_previews.append({'face_id': group['face_id'], 'group_id': group['group_id'],
                              'preview': relative, 'reference_mask': group['mask']})
    record = {'task_hash': ctx['binding']['task_hash'], 'target_id': row['target_id'],
              'target_key': row['target_key'], 'appearance_class': name, 'frame_id': row['frame_id'],
              'frame_key': key, 'split': row['split'], 'group_id': row['group_id'], 'domain': row['domain'],
              'bbox': row['bbox'], 'box_index': row['box_index'], 'width': size[1], 'height': size[0],
              'selection_order': row['selection_order'], 'pixel_rotation_degrees': meta['pixel_rotation_degrees'],
              'reconstructed_intensity': meta['reconstructed_intensity'],
              'image': prefix+'.png', 'annotation': prefix+'.json', 'preview': preview_path,
              'face_previews': face_previews,
              'ignore_mask': ignore_path, 'ignore_pixels': int(ignore.sum()), 'ignored_parents': len(ignored),
              'face_overlap_pixels': int(face_overlap.sum()), 'ignore_overlap_pixels': int(ignore_overlap.sum()),
              'faces': groups, 'face_instances': len(groups), 'review_reasons': reasons,
              'redraw_required': not bool(groups), 'human_reviewed': False, 'mask_human_reviewed': False,
              'proposal_only': True, 'segmentation_training_eligible': False,
              'files': files, 'source_files': source_files}
    protected_write(record_path, encoded(record))
    return record


def csv_bytes(rows, columns):
    stream = io.StringIO(newline='')
    writer = csv.DictWriter(stream, fieldnames=columns, extrasaction='ignore')
    writer.writeheader()
    for row in rows:
        writer.writerow({k: json.dumps(v, ensure_ascii=False) if isinstance(v, (dict, list)) else v
                         for k, v in row.items() if k in columns})
    return b'\xef\xbb\xbf'+stream.getvalue().encode()


def run_export(ctx):
    selected = jsonl(ctx['output']/'selection.jsonl')
    if (ctx['delivery']/'selection.jsonl').exists() and (ctx['delivery']/'selection.jsonl').read_bytes() != (ctx['output']/'selection.jsonl').read_bytes():
        raise ValueError('Frozen seed selection changed')
    records = []
    for i, row in enumerate(selected, 1):
        records.append(export_target(ctx, row))
        if i % 40 == 0 or i == len(selected): log('export', completed=i, total=len(selected))
    summary = {'targets': len(records), 'frames': len({r['frame_id'] for r in records}),
               'appearance_classes': len({r['appearance_class'] for r in records}),
               'per_cluster': ctx['args'].per_cluster, 'seed': ctx['args'].seed,
               'source_splits': dict(Counter(r['split'] for r in records)),
               'face_instances': sum(r['face_instances'] for r in records),
               'redraw_targets': sum(r['redraw_required'] for r in records),
               'frames_with_other_parents': sum(r['ignored_parents'] > 0 for r in records),
               'ignored_parents': sum(r['ignored_parents'] for r in records),
               'frames_with_face_overlap': sum(r['face_overlap_pixels'] > 0 for r in records),
               'frames_with_ignore_overlap': sum(r['ignore_overlap_pixels'] > 0 for r in records),
               'rotation_180_frames': sum(r['pixel_rotation_degrees'] == 180 for r in records),
               'reconstructed_intensity_frames': sum(r['reconstructed_intensity'] for r in records),
               'native_size_counts': dict(Counter(f'{r["width"]}x{r["height"]}' for r in records)),
               'proposal_only': True, 'human_reviewed': False, 'mask_human_reviewed': False,
               'segmentation_training_eligible': False, 'segmentation_accuracy': None}
    delivery = ctx['delivery']
    public = [{k: v for k, v in r.items() if k not in ('files', 'source_files', 'faces')} for r in records]
    faces = [{**g, 'frame_id': r['frame_id'], 'frame_key': r['frame_key'], 'original_split': r['split'],
              'annotation': r['annotation'], 'image': r['image']} for r in records for g in r['faces']]
    protected_write(delivery/'targets.jsonl', b''.join(encoded(r) for r in public))
    protected_write(delivery/'faces.jsonl', b''.join(encoded(r) for r in faces))
    protected_write(delivery/'targets.csv', csv_bytes(public, ['appearance_class', 'selection_order', 'target_id',
         'frame_id', 'split', 'group_id', 'domain', 'bbox', 'face_instances', 'image', 'annotation', 'ignore_mask',
         'ignored_parents', 'face_overlap_pixels', 'ignore_overlap_pixels', 'redraw_required', 'review_reasons']))
    protected_write(delivery/'faces.csv', csv_bytes(faces, ['appearance_class', 'target_id', 'frame_id',
         'original_split', 'group_id', 'face_id', 'pallet_group_id', 'mask', 'annotation', 'overlap_pixels', 'ignore_overlap_pixels']))
    review = [{'appearance_class': r['appearance_class'], 'target_id': r['target_id'], 'annotation': r['annotation'],
               'human_reviewed': False, 'mask_human_reviewed': False, 'reviewer': '', 'reviewed_at': '',
               'result': 'pending', 'notes': ''} for r in records]
    protected_write(delivery/'review_status.csv', csv_bytes(review, list(review[0])))
    protected_write(delivery/'summary.json', encoded(summary))
    protected_write(delivery/'selection.jsonl', (ctx['output']/'selection.jsonl').read_bytes())
    protected_write(delivery/'selection_summary.json', (ctx['output']/'selection_summary.json').read_bytes())
    protected_write(delivery/'manifest.json', encoded({'binding': ctx['binding'], 'summary': summary}))
    protected_write(delivery/'labels.txt', (LABEL+'\n').encode())
    for name in sorted({r['appearance_class'] for r in records}):
        protected_write(delivery/name/'labels.txt', (LABEL+'\n').encode())
    for filename in ['anylabeling_label_file.py', 'anylabeling_shape.py']:
        protected_write(delivery/'source'/filename, read_checked(ctx['source'], 'source/'+filename, ctx['hashes']))
    for filename in ['cluster_annotation_seed.py', 'fork_face_anylabeling.py', 'fork_face_simplify.py']:
        protected_write(delivery/'source'/filename, Path(__file__).with_name(filename).read_bytes())
    if ctx['font'].exists(): protected_write(delivery/'assets/ReportSans.woff', ctx['font'].read_bytes())
    if ctx['license_file'].exists(): protected_write(delivery/'assets/FONT_LICENSE.txt', ctx['license_file'].read_bytes())
    render_reports(ctx, public, summary)
    return records


INSTRUCTIONS = '''## 打开与人工修正

解压ZIP后，在AnyLabeling打开 `A00/images`，其它A类同理。每类按本报告数量提供原尺寸图像与同名JSON；每帧只安排一个入选托盘。A编号用于均衡抽样与归档，分割类别始终为 `pallet_fork_face`。

每个可见面为独立group_id，`pallet_group_id`与target_id指向父托盘。几何面片可能不等于真实物理面，请人工增删、拆分、合并或重画。新建面的group_id须在本帧唯一，并记录所属父托盘。现有凹包保留外部凹陷、填平内部孔洞；这些是初始建议，不是人工真值。初始最多24顶点的限制不约束人工修正。图册中展开“逐面参考”可查看每个面的单独叠图与原始掩膜。

黄色框定位入选托盘，灰色框表示未选托盘。只修正入选托盘的各个可见面。`ignore_masks`中255表示同帧其它托盘区域，0表示未忽略；后续训练必须读取这些掩膜并屏蔽对应像素的损失。不得直接把整帧当作完整标注输入不支持ignore的训练器。与入选面相交的忽略区域在人工裁定前继续忽略，不自动用正标签覆盖。

`face_overlaps`记录入选面凹包重叠，`selected_ignore_overlaps`记录与忽略区域相交。重叠不是几何归属真值，请人工判断边界。没有面建议的目标保留为待重画正例，空JSON不表示负例。

全部初始human_reviewed=false、mask_human_reviewed=false、proposal_only=true、unreviewed=true、训练资格false。完成该托盘全部面的复核后，在副本勾选human_reviewed与mask_human_reviewed、取消proposal_only与unreviewed，并在review_status.csv记录reviewer、reviewed_at、result和说明。保存文件或修改时间不能自动证明已复核。原几何诊断统计只描述初始建议，人工修改后不能继续作为修正结果的统计。

保留原PNG尺寸、文件名、imagePath、父托盘身份和分组元数据；交回完整修正目录及复核状态表。原始reference_masks仅供参考，后续必须从实际修正JSON重建分割标签。人工误判、无可见面或无法裁决的目标在状态表明确说明，不能当作负例或自动获得训练资格。

## 后续训练依据

本包是独立分割种子集，original_split仅记录正式检测集的来源。本轮不启动训练、不自动改变正式检测标签或划分。人工修正完成后另行核验、冻结分割训练快照，读取ignore_mask并排除未复核、待裁决区域。使用原val/test来源样本训练后，这些样本及其采集组不能作为该分割模型的独立评估依据，应另留没有训练重叠的评估数据。

冻结ZIP应保留，人工在副本修改。重新导出与打包保护已修改文件；需要另一轮数据请指定新的输出目录。入口支持select/export/verify/package/all阶段。
'''


def render_reports(ctx, records, summary):
    coverage = json_value(ctx['output']/'selection_summary.json')['coverage']
    lines = ['# 按A类的逐面分割标注种子集', '',
             f'共{summary["appearance_classes"]}类，每类{summary["per_cluster"]}个托盘，'
             f'{summary["targets"]}个目标、{summary["frames"]}张不同原始帧、{summary["face_instances"]}个初始面实例。', '',
             '来源划分：'+json.dumps(summary['source_splits'], ensure_ascii=False)+'。原划分是来源记录，不是新分割训练划分。', '',
             f'其他托盘{summary["ignored_parents"]}个，分布于{summary["frames_with_other_parents"]}帧；'
             f'逐面凹包重叠{summary["frames_with_face_overlap"]}帧，与忽略区域相交{summary["frames_with_ignore_overlap"]}帧；'
             f'待重画{summary["redraw_targets"]}个目标。', '',
             f'固定seed{summary["seed"]}，来源优先train→val→test，轮换采集组与配置域后按缓存外观特征最远点抽样。'
             '匹配检查保证每类配额和全局原帧唯一。特征距离仅描述抽样覆盖，不表示分割正确率。', '',
             '| A类 | 托盘数 | 初始面数 | 已选/可用采集组 | 原划分 | 特征覆盖距离P50/P90 |',
             '|---|---:|---:|---:|---|---|']
    for c in coverage:
        subset = [r for r in records if r['appearance_class'] == c['appearance_class']]
        q = c['nearest_selected_feature_distance_p50_p90_max']
        lines.append(f'| {c["appearance_class"]} | {c["selected_targets"]} | {sum(r["face_instances"] for r in subset)} | '
                     f'{c["selected_groups"]}/{c["available_groups"]} | {json.dumps(c["source_splits"])} | {q[0]:.3f}/{q[1]:.3f} |')
    lines.extend(['', INSTRUCTIONS])
    markdown = '\n'.join(lines)+'\n'
    protected_write(ctx['delivery']/'README_zh.md', markdown.encode())
    protected_write(ctx['delivery']/'report_zh.md', markdown.encode())
    from markdown_it import MarkdownIt
    content = MarkdownIt('commonmark', {'html': False}).enable('table').render(markdown)
    protected_write(ctx['delivery']/'report_zh.html', page('标注种子集报告', f'<a href="gallery.html">浏览{summary["targets"]}个目标</a> · <a href="README_zh.md">标注说明</a><article>{content}</article>'))
    classes = sorted({r['appearance_class'] for r in records})
    reasons = sorted({reason for r in records for reason in r['review_reasons']})
    options = lambda values: ''.join(f'<option value="{html.escape(v, quote=True)}">{html.escape(v)}</option>' for v in values)
    controls = (f'<div class="controls"><label>A类<select id="class"><option value="">全部{len(classes)}类</option>'+options(classes)+
                '</select></label><label>来源<select id="split"><option value="">全部来源</option>'+options(list(SPLITS))+
                '</select></label><label>复核原因<select id="reason"><option value="">全部原因</option>'+options(reasons)+
                '</select></label><label>检索<input id="search" placeholder="目标身份／采集组"></label></div>')
    data = json.dumps(records, ensure_ascii=False, separators=(',', ':'), sort_keys=True).replace('<', '\\u003c')
    script = '''
const records=DATA, esc=s=>String(s).replace(/[&<>"']/g,c=>({'&':'&amp;','<':'&lt;','>':'&gt;','"':'&quot;',"'":'&#39;'}[c]));
let pageIndex=0;const pageSize=20;
function render(){const cls=document.getElementById('class').value,sp=document.getElementById('split').value,reason=document.getElementById('reason').value,q=document.getElementById('search').value.toLowerCase();
const filtered=records.filter(r=>(!cls||r.appearance_class===cls)&&(!sp||r.split===sp)&&(!reason||r.review_reasons.includes(reason))&&(!q||JSON.stringify([r.target_id,r.group_id,r.domain]).toLowerCase().includes(q)));
const pages=Math.max(1,Math.ceil(filtered.length/pageSize));pageIndex=Math.min(pageIndex,pages-1);
document.getElementById('count').textContent=`${filtered.length} 个目标 · 第 ${pageIndex+1}/${pages} 页`;
document.getElementById('prev').disabled=pageIndex===0;document.getElementById('next').disabled=pageIndex>=pages-1;
document.getElementById('cards').innerHTML=filtered.slice(pageIndex*pageSize,(pageIndex+1)*pageSize).map(r=>`<section class="card"><a class="preview" href="${esc(r.preview)}" data-zoom><img src="${esc(r.preview)}" alt="${esc(r.appearance_class)} 面与原框定位" loading="lazy"></a><div><h2>${esc(r.appearance_class)} · 第${r.selection_order}个 · ${r.face_instances}面</h2><p>${esc(r.split)} · ${esc(r.domain)} · 其他托盘${r.ignored_parents}个</p><p class="identity">${esc(r.target_id)}</p><p class="reasons">${r.review_reasons.map(esc).join(' · ')}</p><nav><a href="${esc(r.image)}">原图</a><a href="${esc(r.annotation)}" download>JSON</a><a href="${esc(r.ignore_mask)}">忽略区域</a><a href="${esc(r.annotation.split('/images/')[0]+'/images/')}">A类目录</a></nav><details><summary>逐面参考（${r.face_instances}面）</summary><ul>${r.face_previews.map(f=>`<li>面 ${f.face_id}：<a href="${esc(f.preview)}" data-zoom>单面叠图</a> · <a href="${esc(f.reference_mask)}">原始掩膜</a></li>`).join('')}</ul></details></div></section>`).join('');}
document.querySelectorAll('select,input').forEach(e=>e.addEventListener(e.tagName==='INPUT'?'input':'change',()=>{pageIndex=0;render()}));
document.getElementById('prev').onclick=()=>{pageIndex--;render()};document.getElementById('next').onclick=()=>{pageIndex++;render()};
const dialog=document.getElementById('zoom');document.getElementById('cards').onclick=e=>{const a=e.target.closest('[data-zoom]');if(a){e.preventDefault();document.getElementById('zoom-image').src=a.href;dialog.showModal()}};
document.getElementById('close').onclick=()=>dialog.close();dialog.onclick=e=>{if(e.target===dialog)dialog.close()};render();
'''.replace('DATA', data, 1)
    body = (f'<h1>按A类的逐面分割标注种子集</h1><p class="intro">{len(classes)}类 · {summary["targets"]}个托盘 · '
            f'{summary["face_instances"]}个初始面 · 全部待人工复核</p>'
            '<nav><a href="report_zh.html">报告与标注规则</a><a href="targets.csv">目标清单</a>'
            '<a href="review_status.csv">人工状态表</a></nav>'+controls+
            '<p id="count" aria-live="polite"></p><div id="cards"></div><div class="pager">'
            '<button id="prev">上一页</button><button id="next">下一页</button></div>'
            '<dialog id="zoom"><button id="close">关闭</button><img id="zoom-image" alt="目标原生定位与逐面叠图"></dialog>'
            '<script>'+script+'</script>')
    protected_write(ctx['delivery']/'gallery.html', page('A类逐面标注图册', body))


def page(title, body):
    style = '''@font-face{font-family:ReportSans;src:url('assets/ReportSans.woff')}*{box-sizing:border-box}body{margin:0;background:#eef2f3;color:#18323d;font:16px ReportSans,system-ui,sans-serif}main{max-width:1500px;padding:30px;margin:auto}h1{font-size:30px;margin:0 0 12px}h2{font-size:18px}a{color:#146b70}nav{display:flex;gap:20px;flex-wrap:wrap}article,.controls{background:white;border-radius:12px;padding:24px;margin-top:24px}article{line-height:1.85;overflow:auto}article table{border-collapse:collapse;font-size:14px}th,td{padding:8px 12px;border-bottom:1px solid #d5dfe0;text-align:left}.controls{display:flex;gap:18px;flex-wrap:wrap;padding:18px}label{display:flex;flex-direction:column;gap:6px}select,input,button{font:inherit;padding:9px;border:1px solid #a4b9bd;border-radius:6px;background:white;max-width:100%}select{max-width:350px}.intro{color:#526e76}#cards{display:grid;grid-template-columns:repeat(auto-fit,minmax(310px,1fr));gap:18px}.card{background:white;border-radius:12px;overflow:hidden}.card>div{padding:18px}.preview{display:block;background:#142e39}.preview img{width:100%;height:245px;object-fit:contain;image-rendering:auto}.identity,.reasons{font-size:12px;overflow-wrap:anywhere;color:#527078}.pager{display:flex;justify-content:center;gap:20px;margin-top:26px}button{cursor:pointer}button:disabled{opacity:.45}dialog{border:0;border-radius:12px;max-width:95vw;max-height:95vh;padding:16px}dialog::backdrop{background:#102631c9}dialog img{display:block;max-width:90vw;max-height:80vh;margin-top:10px}dialog button{float:right}@media(max-width:600px){main{padding:16px}h1{font-size:24px}#cards{grid-template-columns:1fr}.controls>*{width:100%}select{max-width:100%}.preview img{height:220px}article{padding:16px}}@media print{body{background:white}main{padding:0}nav,.controls,.pager{display:none}article{padding:0}tr{break-inside:avoid}}
'''
    return (f'<!doctype html><html lang="zh-CN"><head><meta charset="utf-8"><meta name="viewport" '
            f'content="width=device-width,initial-scale=1"><title>{html.escape(title)}</title><style>{style}</style>'
            f'</head><body><main>{body}</main></body></html>\n').encode()


def recheck_inputs(ctx, records):
    checked = 0
    for path, expected in ctx['binding']['inputs'].items():
        if digest(path) != expected: raise ValueError(f'Frozen input changed: {path}')
        checked += 1
    used = {p: sha for r in records for p, sha in r['source_files'].items()}
    for relative, expected in used.items():
        if digest(safe_path(ctx['source'], relative)) != expected:
            raise ValueError(f'Frozen source changed: {relative}')
    for relative, expected in ctx['cluster_hashes'].items():
        if digest(safe_path(ctx['clustering'], relative)) != expected:
            raise ValueError(f'Historical cluster result changed: {relative}')
    receipt_path = ctx['source'].parent/'delivery_manifest.json'
    archives = 0
    if receipt_path.exists():
        receipt = json_value(receipt_path)
        archive = safe_path(ctx['source'].parent, receipt['archive_name'])
        if digest(archive) != receipt['archive_sha256']:
            raise ValueError('Historical segmentation ZIP changed')
        archives = 1
    protected = ctx['formal'].get('protected_files', {})
    if protected:
        dataset = Path(ctx['formal']['binding']['dataset'])
        for relative, expected in protected.items():
            if digest(safe_path(dataset, relative)) != expected:
                raise ValueError(f'Formal detection label/metadata changed: {relative}')
    return {'input_files_unchanged': checked, 'used_segmentation_assets_unchanged': len(used),
            'historical_clustering_files_unchanged': len(ctx['cluster_hashes']),
            'protected_formal_files_unchanged': len(protected), 'historical_segmentation_archives_unchanged': archives}


def records_for(ctx):
    if (ctx['output']/'selection.jsonl').read_bytes() != (ctx['delivery']/'selection.jsonl').read_bytes():
        raise ValueError('Frozen seed selection changed')
    selection = jsonl(ctx['output']/'selection.jsonl')
    result = [json_value(ctx['output']/'records'/r['appearance_class']/(ctx['frames'][r['frame_id']]['frame_key']+'.json'))
              for r in selection]
    for r in result:
        if r['task_hash'] != ctx['binding']['task_hash']: raise ValueError('Record task binding changed')
        for path, expected in r['files'].items():
            if digest(safe_path(ctx['delivery'], path)) != expected:
                raise ValueError(f'Completed file changed; human edits are protected: {path}')
    return result


def run_verify(ctx):
    records, delivery = records_for(ctx), ctx['delivery']
    selected, _, _ = select_targets(ctx['rows'], ctx['features'], ctx['args'].per_cluster, ctx['args'].seed)
    if b''.join(encoded(r) for r in selected) != (ctx['output']/'selection.jsonl').read_bytes():
        raise ValueError('Repeated sample selection differs')
    if len({r['target_id'] for r in records}) != len(records) or len({r['frame_id'] for r in records}) != len(records):
        raise ValueError('Duplicate target or native frame')
    counts = Counter(r['appearance_class'] for r in records)
    if set(counts) != {f'A{c:02d}' for c in ctx['binding']['cluster_ids']} or any(n != ctx['args'].per_cluster for n in counts.values()):
        raise ValueError('Per-cluster target coverage failed')
    summary = json_value(delivery/'summary.json')
    official_saves = 0
    with tempfile.TemporaryDirectory(prefix='cluster-seed-save-') as temporary:
        for number, r in enumerate(records, 1):
            path = delivery/r['annotation']
            doc = json_value(path); meta = doc['pallet_segmentation']
            with Image.open(delivery/r['image']) as image:
                if (image.width, image.height) != (doc['imageWidth'], doc['imageHeight']):
                    raise ValueError('Image and JSON native sizes disagree')
            if (path.parent/doc['imagePath']).resolve() != (delivery/r['image']).resolve():
                raise ValueError('Nonportable AnyLabeling imagePath')
            if len(meta['parents']) != 1 or meta['parents'][0]['target_id'] != r['target_id'] or meta['parents'][0]['bbox'] != r['bbox']:
                raise ValueError('Selected parent identity changed')
            if meta['appearance_class'] != r['appearance_class'] or meta['original_split'] != r['split']:
                raise ValueError('Cluster or original split provenance changed')
            flags = doc['flags']
            if (flags['human_reviewed'] or flags['mask_human_reviewed'] or flags['segmentation_training_eligible']
                    or not flags['proposal_only'] or not flags['unreviewed'] or flags['confirmed_negative']):
                raise ValueError('Initial proposals were promoted to reviewed training labels')
            size = (doc['imageHeight'], doc['imageWidth'])
            pixels = raster_groups(doc, size, ctx['upstream'])
            groups = {g['group_id']: g for g in meta['groups']}
            if set(pixels) != set(groups) or len(groups) != r['face_instances']:
                raise ValueError('Face identity coverage changed')
            combined = np.zeros(size, np.int32)
            for group_id, mask in pixels.items():
                group = groups[group_id]
                if group['target_id'] != r['target_id'] or group['pallet_group_id'] != r['box_index']+1 or group['face_id'] != group_id:
                    raise ValueError('Face/parent mapping changed')
                raw = np.asarray(Image.open(delivery/group['mask']))
                if raw.shape != size or ((raw > 0) & ~mask).any(): raise ValueError('Reference face evidence lost')
                combined += mask
            source_doc = json.loads(read_checked(ctx['source'], ctx['frames'][r['frame_id']]['views']['faces']['annotation'], ctx['hashes']))
            expected_ignore, ignored = ignore_regions(source_doc['pallet_segmentation']['parents'], r['target_id'], size)
            for relative, expected in [(r['ignore_mask'], expected_ignore),
                 (meta['face_overlap_mask'], combined > 1),
                 (meta['selected_ignore_overlap_mask'], (combined > 0) & expected_ignore)]:
                actual = np.asarray(Image.open(delivery/relative))
                if not np.array_equal(actual, expected.astype(np.uint8)*255):
                    raise ValueError('Ignore or overlap diagnostics changed')
            if len(ignored) != r['ignored_parents'] or flags['unresolved_positive'] != (len(groups) == 0):
                raise ValueError('Ignored parent or unresolved-positive status changed')
            official_saves += 1
            check_label_save(path, Path(temporary)/'saved.json', ctx['label_class'])
            if number % 100 == 0 or number == len(records): log('verify', completed=number, total=len(records))
    public = jsonl(delivery/'targets.jsonl')
    faces = jsonl(delivery/'faces.jsonl')
    if [r['target_id'] for r in public] != [r['target_id'] for r in records] or len(faces) != summary['face_instances']:
        raise ValueError('Public target/face index coverage failed')
    protection = recheck_inputs(ctx, records)
    assets = {str(p.relative_to(delivery)): digest(p) for p in sorted(delivery.rglob('*')) if p.is_file()
              and p.name not in ('verified_assets.json', 'validation.json', 'checksums.sha256')}
    protected_write(delivery/'verified_assets.json', encoded({'task_hash': ctx['binding']['task_hash'], 'files': assets}))
    validation = {'state': 'passed', 'task_hash': ctx['binding']['task_hash'], 'targets_checked': len(records),
                  'unique_native_frames': len(records), 'per_class_counts': dict(counts),
                  'source_splits': dict(Counter(r['split'] for r in records)), 'face_instances_checked': len(faces),
                  'official_anylabeling_load_save_documents': official_saves, 'gui_application_tested': False,
                  'sampling_reproducible': True, 'native_coordinates_preserved': True,
                  'ignore_and_overlap_masks_verified': True, 'initial_training_eligibility_false': True,
                  **protection, 'verified_assets_sha256': digest(delivery/'verified_assets.json')}
    protected_write(delivery/'validation.json', encoded(validation))
    protected_write(ctx['output']/'validation.json', encoded(validation))
    return validation


def run_package(ctx):
    output, delivery = ctx['output'], ctx['delivery']
    validation = json_value(output/'validation.json')
    frozen = json_value(delivery/'verified_assets.json')
    if validation['task_hash'] != ctx['binding']['task_hash'] or digest(delivery/'verified_assets.json') != validation['verified_assets_sha256']:
        raise ValueError('Validated task or asset registry changed')
    assets = frozen['files']
    expected_paths = set(assets) | {'verified_assets.json', 'validation.json', 'checksums.sha256'}
    actual_paths = {str(p.relative_to(delivery)) for p in delivery.rglob('*') if p.is_file()}
    if actual_paths - expected_paths:
        raise ValueError('Unverified files added to annotation workspace; human edits are protected')
    if digest(delivery/'validation.json') != digest(output/'validation.json'):
        raise ValueError('Validation receipt changed')
    for relative, expected in assets.items():
        if digest(safe_path(delivery, relative)) != expected:
            raise ValueError(f'Validated file changed; human edits are protected: {relative}')
    recheck_inputs(ctx, records_for(ctx))
    receipt_path = output/'delivery_manifest.json'
    if receipt_path.exists():
        receipt = json_value(receipt_path)
        if digest(output/receipt['archive_name']) != receipt['archive_sha256']:
            raise ValueError('Published ZIP changed')
        return receipt
    assets = {**assets, 'verified_assets.json': digest(delivery/'verified_assets.json'),
              'validation.json': digest(delivery/'validation.json')}
    protected_write(delivery/'checksums.sha256', ''.join(f'{sha}  {p}\n' for p, sha in sorted(assets.items())).encode())
    assets['checksums.sha256'] = digest(delivery/'checksums.sha256')
    archive = output/'pallet_cluster_annotation_seed_v1.zip'
    temporary = archive.with_suffix('.partial')
    with zipfile.ZipFile(temporary, 'w', compression=zipfile.ZIP_DEFLATED, compresslevel=4) as z:
        for relative, expected in sorted(assets.items()):
            path = safe_path(delivery, relative)
            if digest(path) != expected: raise ValueError('Workspace changed during packaging')
            info = zipfile.ZipInfo(relative, date_time=(2026, 1, 1, 0, 0, 0))
            info.compress_type = zipfile.ZIP_DEFLATED; info.external_attr = 0o644 << 16
            z.writestr(info, path.read_bytes(), compress_type=zipfile.ZIP_DEFLATED, compresslevel=4)
    records = records_for(ctx)
    with zipfile.ZipFile(temporary) as z:
        if len(z.namelist()) != len(assets) or z.testzip() is not None: raise ValueError('ZIP member count/CRC failed')
        for relative, expected in assets.items():
            if hashlib.sha256(z.read(relative)).hexdigest() != expected:
                raise ValueError(f'ZIP member SHA-256 failed: {relative}')
        with tempfile.TemporaryDirectory(prefix='cluster-seed-portable-') as directory:
            for r in records:
                for relative in (r['image'], r['annotation']):
                    path = safe_path(Path(directory), relative); path.parent.mkdir(parents=True, exist_ok=True)
                    path.write_bytes(z.read(relative))
                check_label_save(Path(directory)/r['annotation'], Path(directory)/'saved.json', ctx['label_class'])
    temporary.replace(archive)
    sha = digest(archive)
    protected_write(archive.with_suffix('.zip.sha256'), f'{sha}  {archive.name}\n'.encode())
    receipt = {'state': 'complete', 'task_hash': ctx['binding']['task_hash'], 'archive_name': archive.name,
               'archive_bytes': archive.stat().st_size, 'archive_sha256': sha, 'zip_members': len(assets),
               'crc_passed': True, 'all_member_sha256_passed': True, 'portable_load_save_documents': len(records),
               'validated_files_rechecked_before_package': True, 'validation': validation,
               'summary': json_value(delivery/'summary.json'),
               'finished_at': datetime.now(timezone(timedelta(hours=8))).isoformat()}
    protected_write(receipt_path, encoded(receipt))
    log('package', state='complete', archive=str(archive), archive_bytes=receipt['archive_bytes'])
    return receipt


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--clustering', type=Path, default=DEFAULT_CLUSTERING)
    parser.add_argument('--source', type=Path, default=DEFAULT_SOURCE)
    parser.add_argument('--output', type=Path, default=DEFAULT_OUTPUT)
    parser.add_argument('--per-cluster', type=int, default=10)
    parser.add_argument('--seed', type=int, default=42)
    parser.add_argument('--font', type=Path, help='Optional local licensed WOFF reading font')
    parser.add_argument('--stage', choices=['select', 'export', 'verify', 'package', 'all'], default='all')
    args = parser.parse_args(argv)
    if args.per_cluster < 1: parser.error('--per-cluster must be positive')
    ctx = load_context(args)
    stages = ['select', 'export', 'verify', 'package'] if args.stage == 'all' else [args.stage]
    for stage in stages:
        {'select': run_select, 'export': run_export, 'verify': run_verify, 'package': run_package}[stage](ctx)


if __name__ == '__main__':
    main()
