"""Lossless, resumable AnyLabeling polygon workspaces for measured face masks.

Ordinary AnyLabeling polygons have one ring. Split masks into hole-free pieces,
keep their instance group, and validate their filled pixels rather than dropping
holes, isolated measurements, or thin structures.
"""
from __future__ import annotations

import argparse
import ast
from collections import Counter, defaultdict
from concurrent.futures import ProcessPoolExecutor
from datetime import datetime, timezone
import hashlib
import json
import math
import os
from pathlib import Path, PurePosixPath
import shutil
import time
import zipfile

import cv2
import numpy as np
import PIL.Image
import PIL.ImageDraw


LABEL = 'pallet_fork_face'
VIEWS = ('faces', 'pallets')
_CONTEXT = {}


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


def encoded(value):
    return (json.dumps(value, ensure_ascii=False, separators=(',', ':'),
                       sort_keys=True) + '\n').encode()


def timestamp():
    return datetime.now(timezone.utc).isoformat()


def safe_path(root, relative):
    p = PurePosixPath(relative)
    if p.is_absolute() or '..' in p.parts or '\\' in relative:
        raise ValueError(f'Unsafe relative path: {relative}')
    path = Path(root) / relative
    if not path.resolve().is_relative_to(Path(root).resolve()):
        raise ValueError(f'Path escapes workspace: {relative}')
    return path


def protected_write(path, data):
    """An interrupted export may reuse identical files, never human edits."""
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    if path.exists():
        if path.read_bytes() != data:
            raise ValueError(f'Existing file changed; human edits are protected: {path}')
        return
    temporary = path.with_name(path.name + '.partial')
    temporary.write_bytes(data)
    temporary.replace(path)


def save_status(path, value):
    path = Path(path)
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_suffix('.partial')
    temporary.write_bytes(encoded(value))
    temporary.replace(path)


def check_space(path):
    if shutil.disk_usage(path).free < 50 * 2**30:
        raise RuntimeError('Free space below the 50 GiB reserve')


def read_checked(root, relative, hashes):
    data = safe_path(root, relative).read_bytes()
    if hashlib.sha256(data).hexdigest() != hashes[relative]:
        raise ValueError(f'Frozen source changed: {relative}')
    return data


def rasterize(points, size):
    image = PIL.Image.new('L', (size[1], size[0]))
    PIL.ImageDraw.Draw(image).polygon([tuple(p) for p in points], outline=1, fill=1)
    return np.asarray(image, dtype=bool)


def mask_to_polygons(mask):
    """Exact PIL/AnyLabeling raster round trip; no contour simplification."""
    mask = np.asarray(mask, dtype=np.uint8)
    if mask.ndim != 2:
        raise ValueError('A mask must be two-dimensional')
    stack = [(mask, 0, 0)]
    polygons = []
    while stack:
        part, ox, oy = stack.pop()
        ys, xs = np.nonzero(part)
        if not len(xs):
            continue
        x0, x1 = int(xs.min()), int(xs.max()) + 1
        y0, y1 = int(ys.min()), int(ys.max()) + 1
        part = part[y0:y1, x0:x1]
        ox, oy = ox + x0, oy + y0
        height, width = part.shape
        if part.all():
            # Fractions stay inside the last foreground pixel under PIL's
            # integer raster convention, while singleton/line parts have area.
            points = [[0, 0], [width - .125, 0],
                      [width - .125, height - .125], [0, height - .125]]
        else:
            count, labels, stats, _ = cv2.connectedComponentsWithStats(part, connectivity=4)
            if count > 2:
                for i in range(1, count):
                    x, y, w, h, _ = map(int, stats[i])
                    stack.append(((labels[y:y+h, x:x+w] == i).astype(np.uint8),
                                  ox + x, oy + y))
                continue
            contours, _ = cv2.findContours(part, cv2.RETR_EXTERNAL, cv2.CHAIN_APPROX_SIMPLE)
            points = contours[0][:, 0, :].tolist()
            simple = (len(points) >= 3 and cv2.contourArea(contours[0]) > 0
                      and len({tuple(p) for p in points}) == len(points))
            if not simple or not np.array_equal(rasterize(points, part.shape), part.astype(bool)):
                # A filled outside contour would cover a hole or lose detail.
                # Splitting always decreases the spatial extent; no pixel is
                # added or removed, including diagonal/single-pixel fragments.
                if width >= height:
                    cut = width // 2
                    stack.extend([(part[:, :cut], ox, oy), (part[:, cut:], ox + cut, oy)])
                else:
                    cut = height // 2
                    stack.extend([(part[:cut], ox, oy), (part[cut:], ox, oy + cut)])
                continue
        polygons.append([[x + ox, y + oy] for x, y in points])
    return sorted(polygons, key=lambda p: (min(t[1] for t in p), min(t[0] for t in p), p))


def grouped_pixels(shapes, size, upstream=None):
    """Rasterize each piece in its bounding crop; OR pieces in each group."""
    groups = {}
    for shape in shapes:
        points = np.asarray(shape['points'], dtype=float)
        if (shape['shape_type'] != 'polygon' or shape['label'] != LABEL
                or points.ndim != 2 or points.shape[1] != 2 or len(points) < 3
                or not np.isfinite(points).all()):
            raise ValueError('Invalid polygon')
        if (points.min() < 0 or points[:, 0].max() >= size[1]
                or points[:, 1].max() >= size[0]):
            raise ValueError('Polygon outside the native grid')
        if not shape['flags']['proposal_only'] or shape['flags']['mask_human_reviewed']:
            raise ValueError('Unreviewed masks were promoted to reviewed labels')
        group = shape['group_id']
        if not isinstance(group, int) or isinstance(group, bool) or group <= 0:
            raise ValueError('Invalid instance group')
        x0, y0 = np.floor(points.min(axis=0)).astype(int)
        x1, y1 = np.floor(points.max(axis=0)).astype(int) + 1
        local = (points - [x0, y0]).tolist()
        pixels = (upstream((y1-y0, x1-x0), local, 'polygon') if upstream
                  else rasterize(local, (y1-y0, x1-x0)))
        group_mask = groups.setdefault(group, np.zeros(size, bool))
        group_mask[y0:y1, x0:x1] |= pixels
    return groups


def load_upstream(path, expected):
    """Execute only the pinned upstream pure raster function; Qt is unnecessary."""
    if not path:
        return None
    if digest(path) != expected:
        raise ValueError('Pinned AnyLabeling raster source changed')
    module = ast.parse(Path(path).read_text())
    function = next(n for n in module.body if isinstance(n, ast.FunctionDef)
                    and n.name == 'shape_to_mask')
    scope = {'np': np, 'PIL': PIL, 'math': math}
    exec(compile(ast.Module(body=[function], type_ignores=[]), str(path), 'exec'), scope)
    return scope['shape_to_mask']


def initializer(source, output, binding, source_hashes, upstream_path):
    global _CONTEXT
    cv2.setNumThreads(1)
    from threadpoolctl import threadpool_limits
    limiter = threadpool_limits(limits=1)
    _CONTEXT = dict(source=Path(source), output=Path(output), delivery=Path(output)/'delivery',
                    binding=binding, hashes=source_hashes, limiter=limiter,
                    upstream=load_upstream(upstream_path, binding.get('upstream_source_sha256')))


def decode_mask(data, size):
    mask = cv2.imdecode(np.frombuffer(data, np.uint8), cv2.IMREAD_UNCHANGED)
    if mask is None or mask.shape != size or not np.isin(mask, [0, 255]).all():
        raise ValueError('Invalid binary mask or native size')
    return mask > 0


def make_document(frame, targets, group_records, polygons, view):
    shapes = []
    for group in group_records:
        for part, points in enumerate(polygons[group['group_id']]):
            shapes.append({'label': LABEL, 'points': points, 'group_id': group['group_id'],
                           'shape_type': 'polygon', 'text': f"p{group['pallet_group_id']}/g{group['group_id']}/part{part}",
                           'description': f"p{group['pallet_group_id']}/g{group['group_id']}/part{part}",
                           'flags': {'proposal_only': True, 'mask_human_reviewed': False},
                           'pallet_mask_part': {'pallet_group_id': group['pallet_group_id'],
                                                'face_id': group.get('face_id'), 'part_index': part}})
    unresolved = [t['target_id'] for t in targets if t['status'] == 'unresolved_no_mask']
    return {'version': '0.4.43', 'flags': {'human_reviewed': False, 'mask_human_reviewed': False,
                'unreviewed': True, 'proposal_only': True,
                'confirmed_negative': frame['frame_status'] == 'confirmed_negative',
                'unresolved_positive': bool(unresolved)},
            'shapes': shapes, 'imagePath': frame['frame_key'] + '.png', 'imageData': None,
            'imageWidth': frame['width'], 'imageHeight': frame['height'], 'text': '', 'checked': False,
            'pallet_segmentation': {'schema_version': 1, 'view': view,
                'frame_id': frame['frame_id'], 'frame_key': frame['frame_key'],
                'original_split': frame['split'], 'group_id': frame['group_id'],
                'source_task_hash': frame['task_hash'], 'source_frame_status': frame['frame_status'],
                'source_image': frame['image'], 'pixel_rotation_degrees': frame['pixel_rotation_degrees'],
                'reconstructed_intensity': frame['reconstructed_intensity'],
                'proposal_only': True, 'mask_human_reviewed': False,
                'independent_blind_reference': False, 'unresolved_target_ids': unresolved,
                'parents': [{'pallet_group_id': t['box_index']+1, 'target_id': t['target_id'],
                             'bbox': t['bbox'], 'status': t['status'],
                             'review_reasons': t['review_reasons']} for t in targets],
                'groups': group_records, 'holes_preserved_by_grouped_polygon_pieces': True}}


def record_path(output, frame):
    return Path(output)/'records'/frame['split']/(frame['frame_key']+'.json')


def completed(output, frame, binding):
    path = record_path(output, frame)
    if not path.exists():
        return None
    record = json.loads(path.read_text())
    if record['task_hash'] != binding['task_hash'] or record['frame_id'] != frame['frame_id']:
        raise ValueError('Completed frame identity or task binding changed')
    for relative, expected in record['files'].items():
        if digest(safe_path(Path(output)/'delivery', relative)) != expected:
            raise ValueError(f'Completed file changed; refusing to overwrite human edits: {relative}')
    return record


def convert_frame(job):
    frame, targets, faces = job
    ctx = _CONTEXT
    source, delivery, hashes = ctx['source'], ctx['delivery'], ctx['hashes']
    check_space(ctx['output'])
    size = (frame['height'], frame['width'])
    image = read_checked(source, frame['image'], hashes)
    decoded = cv2.imdecode(np.frombuffer(image, np.uint8), cv2.IMREAD_UNCHANGED)
    if decoded is None or decoded.shape[:2] != size:
        raise ValueError('Native image size mismatch')
    files = {}

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

    view_items = {}
    for view in VIEWS:
        groups, polygons, masks = [], {}, {}
        items = faces if view == 'faces' else targets
        for item in items:
            original = item['mask'] if view == 'faces' else item['union_mask']
            data = read_checked(source, original, hashes)
            mask = decode_mask(data, size)
            reference = 'reference_' + original
            write(reference, data)
            if not mask.any():
                if view == 'faces' or item['status'] != 'unresolved_no_mask':
                    raise ValueError('Unexpected empty candidate mask')
                continue
            group_id = item['face_id'] if view == 'faces' else item['box_index'] + 1
            if group_id in polygons:
                raise ValueError('Duplicate instance group')
            groups.append({'group_id': group_id, 'pallet_group_id': item['box_index'] + 1,
                           'face_id': item.get('face_id'), 'target_id': item['target_id'],
                           'mask': reference, 'mask_sha256': hashes[original],
                           'pixels': int(mask.sum()), 'source_status': item['status']})
            polygons[group_id] = mask_to_polygons(mask)
            masks[group_id] = mask
        document = make_document(frame, targets, groups, polygons, view)
        actual = grouped_pixels(document['shapes'], size)
        if set(actual) != set(masks) or any(not np.array_equal(actual[k], m) for k, m in masks.items()):
            raise ValueError('Polygon conversion changed measured mask pixels')
        prefix = f"{view}/images/{frame['split']}/{frame['frame_key']}"
        write(prefix+'.png', image)
        write(prefix+'.json', encoded(document))
        view_items[view] = {'image': prefix+'.png', 'annotation': prefix+'.json',
                            'groups': len(groups), 'polygons': len(document['shapes']),
                            'vertices': sum(len(s['points']) for s in document['shapes'])}
    for field in ('instances', 'conflicts'):
        original = frame[field]
        write('reference_'+original, read_checked(source, original, hashes))
    record = {'frame_id': frame['frame_id'], 'frame_key': frame['frame_key'], 'split': frame['split'],
              'group_id': frame['group_id'], 'task_hash': ctx['binding']['task_hash'],
              'state': 'success', 'source_frame_status': frame['frame_status'],
              'targets': len(targets), 'unresolved_targets': sum(t['status']=='unresolved_no_mask' for t in targets),
              'views': view_items, 'files': files, 'finished_at': timestamp()}
    protected_write(record_path(ctx['output'], frame), encoded(record))
    return record


def verify_record(record):
    delivery = _CONTEXT['delivery']
    size = None
    counts = Counter()
    for view, paths in record['views'].items():
        document = json.loads(safe_path(delivery, paths['annotation']).read_text())
        image_path = safe_path(delivery, paths['annotation']).parent/document['imagePath']
        if image_path.resolve() != safe_path(delivery, paths['image']).resolve():
            raise ValueError('Nonportable imagePath')
        with PIL.Image.open(image_path) as image:
            image.load()
            size = (image.height, image.width)
        if size != (document['imageHeight'], document['imageWidth']):
            raise ValueError('Image/JSON size mismatch')
        flags = document['flags']
        if flags['human_reviewed'] or flags['mask_human_reviewed'] or not flags['proposal_only'] or not flags['unreviewed']:
            raise ValueError('Incorrect initial review flags')
        if flags['confirmed_negative'] != (record['source_frame_status']=='confirmed_negative'):
            raise ValueError('Empty positive was incorrectly made a negative')
        meta = document['pallet_segmentation']
        if meta['frame_id'] != record['frame_id'] or meta['original_split'] != record['split'] or meta['view'] != view:
            raise ValueError('Frame or split identity changed')
        grouped = grouped_pixels(document['shapes'], size, _CONTEXT['upstream'])
        groups = meta['groups']
        if set(grouped) != {g['group_id'] for g in groups} or len(grouped) != paths['groups']:
            raise ValueError('Incomplete instance grouping')
        ownership = np.zeros(size, np.uint16)
        group_meta = {g['group_id']: g for g in groups}
        for shape in document['shapes']:
            g = group_meta[shape['group_id']]
            part = shape['pallet_mask_part']
            if part['pallet_group_id'] != g['pallet_group_id'] or part['face_id'] != g['face_id']:
                raise ValueError('Face/parent attribution changed')
        for group in groups:
            data = safe_path(delivery, group['mask']).read_bytes()
            if hashlib.sha256(data).hexdigest() != group['mask_sha256']:
                raise ValueError('Reference mask changed')
            expected = decode_mask(data, size)
            actual = grouped[group['group_id']]
            if not np.array_equal(actual, expected) or actual.sum() != group['pixels']:
                raise ValueError('AnyLabeling polygons do not exactly reconstruct the source mask')
            if ownership[actual].any():
                raise ValueError('A pixel was assigned to multiple instances')
            ownership[actual] = group['group_id']
        if view == 'faces':
            with PIL.Image.open(delivery/'reference_instances'/record['split']/(record['frame_key']+'.png')) as image:
                native = np.asarray(image)
            if not np.array_equal(ownership, native):
                raise ValueError('Native face instance IDs changed')
        counts[view+'_groups'] += len(groups)
        counts[view+'_polygons'] += len(document['shapes'])
    return dict(counts)


def load_input(source):
    source = Path(source)
    manifest = json.loads((source/'export_manifest.json').read_text())
    hashes = manifest['files']
    index = {}
    for name in ('frames.jsonl', 'targets.jsonl', 'faces.jsonl'):
        data = read_checked(source, name, hashes)
        index[name] = [json.loads(line) for line in data.splitlines() if line.strip()]
    frames = index['frames.jsonl']
    targets, faces = defaultdict(list), defaultdict(list)
    for t in index['targets.jsonl']:
        targets[t['frame_id']].append(t)
    for f in index['faces.jsonl']:
        if f.get('mask'):
            faces[f['frame_id']].append(f)
    if (len(frames) != manifest['summary']['frames']
            or len({f['frame_id'] for f in frames}) != len(frames)
            or sum(map(len, targets.values())) != manifest['summary']['targets']):
        raise ValueError('Incomplete or duplicate source frames/targets')
    known = {f['frame_id']: f for f in frames}
    for fid, ts in targets.items():
        if fid not in known or len({t['box_index'] for t in ts}) != len(ts):
            raise ValueError('Unknown or duplicate parent target')
        if any(t['split'] != known[fid]['split'] for t in ts):
            raise ValueError('Source split mismatch')
    if set(faces) - set(known):
        raise ValueError('Unknown face frame')
    return manifest, frames, targets, faces


def pool(args, binding, hashes):
    return ProcessPoolExecutor(max_workers=args.workers, initializer=initializer,
        initargs=(str(args.source), str(args.output), binding, hashes, args.upstream_shape_source))


def run_export(args, manifest, frames, targets, faces, binding):
    output, delivery = args.output, args.output/'delivery'
    pending, records = [], []
    for frame in frames:
        record = completed(output, frame, binding)
        if record:
            records.append(record)
        else:
            pending.append((frame, targets[frame['frame_id']], faces[frame['frame_id']]))
    started = time.monotonic()
    with pool(args, binding, manifest['files']) as executor:
        for record in executor.map(convert_frame, pending, chunksize=4):
            records.append(record)
            if len(records) % 256 == 0 or len(records) == len(frames):
                print(json.dumps({'stage':'export','completed':len(records),'total':len(frames),
                                  'elapsed_seconds':round(time.monotonic()-started,2)}), flush=True)
    records.sort(key=lambda r: r['frame_id'])
    protected_write(delivery/'frames.jsonl', b''.join(encoded(r) for r in records))
    for name in ('frames.jsonl','targets.jsonl','faces.jsonl','summary.json'):
        protected_write(delivery/'provenance'/name, read_checked(args.source, name, manifest['files']))
    for view in VIEWS:
        protected_write(delivery/view/'labels.txt', (LABEL+'\n').encode())
    protected_write(delivery/'source'/'fork_face_anylabeling.py', Path(__file__).read_bytes())
    summary = {'state':'exported','frames':len(records),'targets':sum(r['targets'] for r in records),
        'confirmed_negative_frames':sum(r['source_frame_status']=='confirmed_negative' for r in records),
        'unresolved_targets':sum(r['unresolved_targets'] for r in records),'task_hash':binding['task_hash'],
        'splits':dict(Counter(r['split'] for r in records)),
        'views':{view:{key:sum(r['views'][view][key] for r in records) for key in ('groups','polygons','vertices')}
                 for view in VIEWS},'proposal_only':True,'mask_human_reviewed':False,
        'zero_pixel_change':True,'source_geometry_modified':False}
    protected_write(delivery/'manifest.json', encoded({'binding':binding,'summary':summary}))
    protected_write(delivery/'README_zh.md', readme(summary).encode())
    save_status(output/'workflow_status.json', summary)
    return records, summary


def readme(summary):
    return f'''# 叉取面分割建议：AnyLabeling人工修正包

共有{summary['frames']:,}帧，原train/val/test及采集组不变。所有新分割仍待人工复核。

1. 解压ZIP。建议先使用 `pallets/images/train`，在AnyLabeling中打开该图像目录。每个托盘的联合掩膜共用group_id；图像和同名JSON已配对。
2. 需要逐面片修正时，打开 `faces/images/train`。同一面片的多个多边形共用group_id；JSON的pallet_group_id指向父托盘。val/test同理，两版独立保存，不会自动互相更新。
3. 类别均为 `{LABEL}`，形状为polygon。分组对应多个片段，不表示多个托盘。为保留叉孔、缺测和薄结构，掩膜已拆成多个无孔多边形，不能只保留外轮廓或做凸包合并；单个实测像素也被保留。文件中的像素级轮廓未简化，部分图像会有较多片段。
4. 人工框仅在JSON元数据的parents/bbox中保留，不显示为可填充的矩形，避免误当分割面。原263张人工负例保留confirmed_negative标记；正例空掩膜仍为unresolved_positive，不作为负例。
5. 全部文件初始human_reviewed=false、mask_human_reviewed=false、unreviewed=true、proposal_only=true。完成修改后保存JSON；可在工具支持的标志菜单标记已检查，并单独记录每张是否完成，未改动不能自动证明已经检查。
6. `reference_masks`、`reference_instances`、`reference_conflicts`是只读原掩膜与冲突依据，不能当作修改后标签；两版都需要用实际修改的JSON重新生成掩膜。`provenance`保留父框、面参数、源身份和状态。41个无掩膜目标仍须专项处理。

逐面版：{summary['views']['faces']['groups']:,}个几何面片组，{summary['views']['faces']['polygons']:,}个多边形片段。
逐托盘版：{summary['views']['pallets']['groups']:,}个非空托盘组，{summary['views']['pallets']['polygons']:,}个多边形片段。
多边形填充后逐像素与原始二值掩膜一致，孔洞未填充。没有人工掩膜参考，不提供分割正确率。

AnyLabeling格式与光栅转换来源：
[官方LabelFile](https://github.com/vietanhdev/anylabeling/blob/130e44d1b9afd9d54d950cccfd37ce1298ae1a32/anylabeling/views/labeling/label_file.py)、
[官方shape_to_mask](https://github.com/vietanhdev/anylabeling/blob/130e44d1b9afd9d54d950cccfd37ce1298ae1a32/anylabeling/views/labeling/utils/shape.py)。

包内 `validation.json`记录全量还原校验；`sha256sum -c checksums.sha256`核对未修改文件。人工作业后摘要变化是正常的，请保留原ZIP并另交修改后的版本。没有复制原始PCD或改变正式检测标签。
'''


def run_verify(args, manifest, frames, binding):
    records = [completed(args.output, f, binding) for f in frames]
    if any(r is None for r in records):
        raise ValueError('Incomplete export')
    counts = Counter()
    with pool(args, binding, manifest['files']) as executor:
        for i, checked in enumerate(executor.map(verify_record, records, chunksize=4), 1):
            counts.update(checked)
            if i % 1024 == 0 or i == len(records):
                print(json.dumps({'stage':'verify','completed':i,'total':len(records)}), flush=True)
    # All used input assets must still equal their frozen parent export hashes.
    required = set()
    for record in records:
        for relative in record['files']:
            if relative.startswith('reference_'):
                required.add(relative[len('reference_'):])
        required.add(f"images/{record['split']}/{record['frame_key']}.png")
    required.update(['frames.jsonl','targets.jsonl','faces.jsonl','summary.json'])
    for relative in required:
        if digest(safe_path(args.source, relative)) != manifest['files'][relative]:
            raise ValueError(f'Source geometry changed: {relative}')
    previous_path = args.output/'delivery'/'validation.json'
    previous = json.loads(previous_path.read_text()) if previous_path.exists() else {}
    result = {'state':'passed','frames_checked':len(records),'instance_groups_checked':dict(counts),
        'used_source_files_unchanged':len(required),'source_geometry_unchanged':True,
        'polygon_mask_pixel_roundtrip':True,'holes_preserved':True,'native_grid_preserved':True,
        'upstream_shape_to_mask_used':bool(args.upstream_shape_source),
        'upstream_source_sha256':binding.get('upstream_source_sha256'),
        'gui_application_tested':False,'task_hash':binding['task_hash'],
        'finished_at':previous.get('finished_at', timestamp())}
    save_status(args.output/'validation.json', result)
    protected_write(args.output/'delivery'/'validation.json', encoded(result))
    return result


def package(args, binding):
    output, delivery = args.output, args.output/'delivery'
    receipt_path = output/'delivery_manifest.json'
    if receipt_path.exists():
        receipt = json.loads(receipt_path.read_text())
        if receipt['task_hash'] != binding['task_hash'] or digest(output/receipt['archive_name']) != receipt['archive_sha256']:
            raise ValueError('Published archive or binding changed')
        return receipt
    validation = json.loads((output/'validation.json').read_text())
    if validation['state'] != 'passed' or validation['task_hash'] != binding['task_hash']:
        raise ValueError('Full verification is required before packaging')
    check_space(output)
    assets = {str(p.relative_to(delivery)):digest(p) for p in sorted(delivery.rglob('*'))
              if p.is_file() and p.name!='checksums.sha256'}
    protected_write(delivery/'checksums.sha256', ''.join(f'{sha}  {p}\n' for p,sha in assets.items()).encode())
    assets['checksums.sha256'] = digest(delivery/'checksums.sha256')
    archive = output/'pallet_fork_face_anylabeling_v1.zip'
    temporary = archive.with_suffix('.partial')
    with zipfile.ZipFile(temporary, 'w', compression=zipfile.ZIP_DEFLATED, compresslevel=4) as z:
        for i, (relative, expected) in enumerate(assets.items()):
            if i % 512 == 0:
                check_space(output)
            path = safe_path(delivery, relative)
            if digest(path) != expected:
                raise ValueError('Workspace changed during packaging')
            z.write(path, relative)
    with zipfile.ZipFile(temporary) as z:
        if z.testzip() is not None:
            raise ValueError('ZIP CRC failed')
        for relative, expected in assets.items():
            if hashlib.sha256(z.read(relative)).hexdigest() != expected:
                raise ValueError('ZIP member SHA-256 failed')
    temporary.replace(archive)
    sha = digest(archive)
    protected_write(archive.with_suffix('.zip.sha256'), f'{sha}  {archive.name}\n'.encode())
    receipt = {'state':'complete','task_hash':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,'validation':validation,
               'summary':json.loads((delivery/'manifest.json').read_text())['summary'],
               'finished_at':timestamp()}
    save_status(receipt_path, receipt)
    save_status(output/'workflow_status.json', receipt)
    return receipt


def main(argv=None):
    parser = argparse.ArgumentParser(description=__doc__)
    parser.add_argument('--source',type=Path,default=Path('outputs/pallet_fork_face_masks_v1/delivery'))
    parser.add_argument('--output',type=Path,default=Path('outputs/pallet_fork_face_anylabeling_v1'))
    parser.add_argument('--workers',type=int,default=8)
    parser.add_argument('--stage',choices=['all','export','verify','package'],default='all')
    parser.add_argument('--upstream-shape-source')
    parser.add_argument('--upstream-sha256')
    args = parser.parse_args(argv)
    if not 1 <= args.workers <= 8:
        parser.error('workers must be between 1 and 8')
    if bool(args.upstream_shape_source) != bool(args.upstream_sha256):
        parser.error('Pinned upstream source requires both path and SHA-256')
    args.source, args.output = args.source.resolve(), args.output.resolve()
    if args.source.is_relative_to(args.output) or args.output.is_relative_to(args.source):
        parser.error('Source and output must be independent directories')
    args.output.mkdir(parents=True,exist_ok=True)
    check_space(args.output)
    manifest, frames, targets, faces = load_input(args.source)
    binding = {'source_export_manifest_sha256':digest(args.source/'export_manifest.json'),
        'source_task_hash':manifest['task_hash'],'source_code_sha256':digest(__file__),
        'source_index_hashes':{p:manifest['files'][p] for p in ('frames.jsonl','targets.jsonl','faces.jsonl','summary.json')},
        'views':VIEWS,'label':LABEL,'algorithm':'exact_component_contour_recursive_partition_v1',
        'upstream_source_sha256':args.upstream_sha256}
    binding['task_hash'] = hashlib.sha256(encoded(binding)).hexdigest()
    protected_write(args.output/'run_manifest.json',encoded(binding))
    for stage in (['export','verify','package'] if args.stage=='all' else [args.stage]):
        if stage=='export':run_export(args,manifest,frames,targets,faces,binding)
        elif stage=='verify':run_verify(args,manifest,frames,binding)
        else:print(json.dumps(package(args,binding),ensure_ascii=False),flush=True)


if __name__ == '__main__':
    main()
