"""Import manual AnyLabeling corrections, train an isolated assistant, and package candidates."""
from __future__ import annotations

import argparse
from collections import Counter
from concurrent.futures import ThreadPoolExecutor
from dataclasses import asdict, replace
from datetime import datetime, timezone
import hashlib
import json
import math
import os
from pathlib import Path, PurePosixPath
import shutil
import subprocess
import sys
import tempfile
import time
import zipfile

import numpy as np
from PIL import Image
import torch
from torch.utils.data import DataLoader, Dataset

from pallet.annotation import (AnnotationSet, Box, FrameAnnotation, Provenance, SceneAttributes, annotation_digest,
                               is_resolved, load_jsonl, save_jsonl)
from pallet.cli import _attach_cache, _records, _validate_annotation_protocol
from pallet.data.loader import NormalizationStats, apply_normalization, fit_normalization, load_frame
from pallet.data.protocol import file_digest, load_protocol, write_json
from pallet.devices import device_metadata, pinned_cuda_metadata, resolve_device
from pallet.experiments.dataset import SampleMeta, letterbox_float
from pallet.experiments.evaluate import _count_matches, predict_boxes, predict_batch_boxes
from pallet.data.eligibility import active_policy
from pallet.export import load_detector_checkpoint
from pallet.review_batches import display
from pallet.research_log import collect_references


DEFAULT_SOURCE_EXPORT = Path('outputs/anylabeling/pallet_v5_20260930')
DEFAULT_PARENT = Path('outputs/rounds_v5/round_005/labels/round-005-reviewed.jsonl')
DEFAULT_ROOT = Path('/root/private/data/pallet')
DEFAULT_OUTPUT = Path('outputs/human_correction_v1')
DEFAULT_MANUAL_OUTPUT = Path('outputs/human_correction_manual_v3')
DEFAULT_MANUAL_1330_OUTPUT = Path('outputs/human_correction_manual_1330_v1')
RTX3090_UUID = 'GPU-3ce8e1e7-efb2-80a6-de52-75da2f9fa259'
CONFIDENCE_GRID = (0.05, 0.10, 0.20, 0.30, 0.50, 0.70)
AUXILIARY_SCOPE = 'human_annotation_assistance_only'
AUXILIARY_TRAIN_KIND = 'explicit_user_confirmed_cross_split_annotation_assistant_training'
AUXILIARY_VAL_KIND = 'explicit_user_confirmed_cross_split_annotation_assistant_validation'


def is_auxiliary_manifest(manifest):
    """Cross-split labels are usable only in the explicitly isolated assistant branch."""
    return (manifest.get('kind') in {AUXILIARY_TRAIN_KIND, AUXILIARY_VAL_KIND}
            and manifest.get('scope') == AUXILIARY_SCOPE
            and manifest.get('original_splits_preserved') is True
            and manifest.get('eligible_for_research_evaluation') is False
            and manifest.get('approver') == 'user_confirmed_in_conversation')


MODEL_CONFIG = {'family': 'yolo26', 'seed': 42, 'size': 640, 'batch_size': 4,
                'effective_batch': 16, 'epochs': 300, 'patience': 50,
                'recipe': 'official_research_constrained', 'pretrained': 'yolo26s.pt',
                'p2': False, 'fusion': False, 'edge': False, 'mosaic': False,
                'augmentation': True}


def _sha(value: bytes) -> str:
    return hashlib.sha256(value).hexdigest()


def _write_jsonl(path: Path, rows) -> None:
    path.parent.mkdir(parents=True, exist_ok=True)
    temporary = path.with_name(path.name + '.tmp')
    with temporary.open('w', encoding='utf-8') as stream:
        for row in rows:
            stream.write(json.dumps(row, ensure_ascii=False, sort_keys=True) + '\n')
        stream.flush()
        os.fsync(stream.fileno())
    os.replace(temporary, path)


def _load_frame_index(source_export: Path):
    manifest_path = source_export/'manifest.json'
    package_path = source_export/'package_manifest.json'
    index_path = source_export/'frames.jsonl'
    if manifest_path.is_file():
        manifest_path_used = manifest_path
    elif package_path.is_file():
        manifest_path_used = package_path
    else:
        raise FileNotFoundError(f'no source manifest in {source_export}')
    manifest = json.loads(manifest_path_used.read_text())
    if manifest.get('kind') == 'formal_user_reviewed_pallet_dataset':
        # Formal releases keep the index/protocol fingerprints in their complete
        # payload table. Adapt the read interface without changing the frozen
        # manifest or granting assistant-training/blind-reference eligibility.
        files = manifest.get('files', {})
        if (manifest.get('state') != 'frozen' or 'frames.jsonl' not in files
                or 'protocol/protocol.json' not in files
                or 'frames' not in manifest.get('summary', {})):
            raise ValueError('Incomplete formal dataset manifest')
        manifest = {**manifest, 'frames': manifest['summary']['frames'],
            'frames_index_sha256': files['frames.jsonl'],
            'binding': {'protocol_sha256': files['protocol/protocol.json']}}
    if file_digest(index_path) != manifest['frames_index_sha256']:
        raise ValueError('AnyLabeling frame index hash mismatch')
    index = {}
    by_filename = {}
    for line in index_path.read_text().splitlines():
        row = json.loads(line)
        if row['frame_id'] in index or Path(row['annotation']).name in by_filename:
            raise ValueError('duplicate frame or label filename in source export index')
        if 'size' not in row:
            annotation_path = source_export/row['annotation']
            if not annotation_path.is_file():
                raise FileNotFoundError(f'missing baseline proposal JSON: {annotation_path}')
            document = json.loads(annotation_path.read_text())
            metadata = document.get('pallet_export') or document.get('pallet_prediction') or {}
            if metadata.get('frame_id') != row['frame_id']:
                raise ValueError(f'proposal source identity mismatch: {row["frame_id"]}')
            row = {**row, 'size': [document.get('imageWidth'), document.get('imageHeight')],
                   'source_status': row.get('source_status', row.get('source_state', row.get('state'))),
                   'source_metadata': metadata}
        index[row['frame_id']] = row
        by_filename[Path(row['annotation']).name] = row
    if len(index) != manifest['frames']:
        raise ValueError('incomplete AnyLabeling source index')
    protocol_hash = (manifest.get('binding', {}).get('protocol_sha256')
                     or manifest.get('prediction_binding', {}).get('protocol_sha256'))
    return manifest, index, by_filename, file_digest(manifest_path_used), file_digest(index_path)


def _decode_rectangles(document, width, height):
    boxes = []
    for shape in document.get('shapes', []):
        if shape.get('label') != 'pallet' or shape.get('shape_type') != 'rectangle':
            raise ValueError('manual training corrections must contain pallet rectangles only')
        points = np.asarray(shape.get('points'), dtype=np.float64)
        if points.shape not in {(2, 2), (4, 2)} or not np.isfinite(points).all():
            raise ValueError('expected a finite AnyLabeling rectangle with two or four points')
        x1, y1 = points.min(axis=0)
        x2, y2 = points.max(axis=0)
        box = Box(float(x1), float(y1), float(x2-x1), float(y2-y1))
        box.validate(width, height)
        boxes.append(box)
    return boxes


def _reference_validation(root, protocol, records, assignments):
    sources, coverage = collect_references(root, protocol=protocol)
    if coverage['val']['payload_conflicts'] or coverage['val']['status_conflicts']:
        raise ValueError('independent validation references have content conflicts')
    selected = {}
    for source in sources:
        if source['split'] != 'val' or not source['verified']:
            continue
        labels_path = root/source['path']
        labels = load_jsonl(labels_path)
        for fid, frame in labels.frames.items():
            if fid in selected and annotation_digest(selected[fid][0]) != annotation_digest(frame):
                raise ValueError(f'validation reference conflict: {fid}')
            selected[fid] = (frame, labels_path)
    by_id = {row.frame_id: row for row in records}
    result = AnnotationSet()
    for fid, (frame, _) in sorted(selected.items()):
        source = by_id.get(fid)
        if (source is None or assignments[source.group_id] != 'val' or frame.split != 'val'
                or frame.group_id != source.group_id or frame.source_anchor_hash != source.source_sha256
                or not is_resolved(frame, require_blind=True)):
            raise ValueError(f'invalid independent validation identity: {fid}')
        result.add(frame)
    scorable = sum(f.status in {'pos', 'negative'} for f in result.frames.values())
    if len(result.frames) != 596 or scorable != 463:
        raise ValueError(f'frozen validation coverage changed: frames={len(result.frames)}, scorable={scorable}')
    return result, sources, coverage


def import_corrections(*, archive, source_export=DEFAULT_SOURCE_EXPORT,
                       protocol='outputs/protocol_v5', parent_labels=DEFAULT_PARENT,
                       root=DEFAULT_ROOT, output=DEFAULT_OUTPUT):
    """Validate the returned archive and publish a fresh, immutable manual-label stage."""
    archive, source_export, protocol, parent_labels = map(Path,
        (archive, source_export, protocol, parent_labels))
    root, output = Path(root).resolve(), Path(output).resolve()
    if output.exists() and (output/'import_manifest.json').exists():
        current = json.loads((output/'import_manifest.json').read_text())
        inputs = {'archive_sha256': file_digest(archive),
                  'source_export_manifest_sha256': file_digest(source_export/'manifest.json'),
                  'frame_index_sha256': file_digest(source_export/'frames.jsonl'),
                  'protocol_sha256': file_digest(protocol/'protocol.json'),
                  'parent_labels_sha256': file_digest(parent_labels)}
        if current.get('inputs') != inputs:
            raise ValueError('import workspace is bound to different input versions; choose a new output')
        for relative, expected in current.get('artifacts', {}).items():
            path = output/relative
            if not path.is_file() or file_digest(path) != expected:
                raise ValueError(f'imported immutable artifact changed: {relative}')
        return current
    if output.exists() and any(output.iterdir()):
        raise ValueError('import output exists but is not a matching resumable stage')

    source_manifest, frame_index, by_filename, source_manifest_sha, index_sha = _load_frame_index(source_export)
    records, assignments, protocol_data = load_protocol(protocol)
    if source_manifest['binding']['protocol_sha256'] != file_digest(protocol/'protocol.json'):
        raise ValueError('AnyLabeling export is not bound to this frozen protocol')
    base = load_jsonl(parent_labels)
    if set(base.frames) != {row.frame_id for row in records}:
        raise ValueError('parent snapshot does not cover all frozen protocol frames')
    for row in records:
        frame = base.frames[row.frame_id]
        if (frame.group_id != row.group_id or frame.source_anchor_hash != row.source_sha256
                or frame.split != assignments[row.group_id]):
            raise ValueError(f'parent snapshot identity mismatch: {row.frame_id}')

    # The train snapshot contains only the 306 explicitly attested frames.
    # Validation records are joined separately from blind, frozen references.
    staged = AnnotationSet()

    archive_rows = []
    archive_names = set()
    source_frames = {}
    with zipfile.ZipFile(archive) as bundle:
        for item in bundle.infolist():
            if item.is_dir():
                continue
            path = PurePosixPath(item.filename)
            if path.name != item.filename or path.suffix.lower() != '.json':
                raise ValueError(f'archive contains unexpected member: {item.filename}')
            if item.filename in archive_names:
                raise ValueError(f'duplicate label in archive: {item.filename}')
            archive_names.add(item.filename)
            raw = bundle.read(item)
            document = json.loads(raw)
            row = by_filename.get(item.filename)
            if row is None:
                raise ValueError(f'label filename is not in the source export: {item.filename}')
            metadata = document.get('pallet_export') or {}
            fid = metadata.get('frame_id')
            from pallet.data.eligibility import exclusion_ids
            if fid in exclusion_ids():
                raise ValueError(f'Frame retired from annotation dataset: {fid}')
            if fid != row['frame_id'] or Path(row['annotation']).name != item.filename:
                raise ValueError(f'frame identity mismatch in {item.filename}')
            original = json.loads((source_export/row['annotation']).read_text())
            if (file_digest(source_export/row['annotation']) != row['baseline_json_sha256']
                    or metadata.get('source_anchor_hash') != row['source_anchor_hash']
                    or row['source_status'] != original['pallet_export']['source_status']):
                raise ValueError(f'source export JSON/hash mismatch: {fid}')
            if (document.get('imageWidth'), document.get('imageHeight')) != tuple(row['size']):
                raise ValueError(f'native dimensions changed: {fid}')
            if document.get('imagePath') != original.get('imagePath'):
                raise ValueError(f'image pairing changed: {fid}')
            if row['split'] != 'train' or metadata.get('source_status') not in {
                    'unreviewed', 'proposal', 'pos', 'negative', 'ignore'}:
                raise ValueError(f'manual training archive contains a nontraining frame: {fid}')
            boxes = _decode_rectangles(document, row['size'][0], row['size'][1])
            if not boxes:
                status = 'negative'
            else:
                status = 'pos'
            frame = base.frames[fid]
            frame = replace(frame, status=status, boxes=boxes, ignore_regions=[], reviews=[])
            frame.provenance = [*frame.provenance, Provenance(
                source='human', actor='user_confirmed_archive_import',
                note=f'train.zip manually corrected labels; archive sha256={file_digest(archive)}')]
            frame.validate()
            if fid not in staged.frames:
                staged.add(frame)
            else:
                staged.frames[fid] = frame
            source_frames[fid] = {'group_id': row['group_id'],
                'source_anchor_hash': row['source_anchor_hash'], 'split': row['split'],
                'width': row['size'][0], 'height': row['size'][1], 'status': status,
                'instances': len(boxes), 'annotation_digest': annotation_digest(frame),
                'source_json_sha256': _sha(raw), 'source_export_json_sha256': file_digest(source_export/row['annotation'])}
            archive_rows.append({'frame_id': fid, **source_frames[fid]})
    if len(archive_rows) != 306 or len(source_frames) != 306:
        raise ValueError(f'expected exactly 306 manually corrected frames; found {len(archive_rows)}')
    counts = Counter(row['status'] for row in archive_rows)
    if counts != Counter({'pos': 303, 'negative': 3}) or sum(r['instances'] for r in archive_rows) != 324:
        raise ValueError(f'manual correction content differs from inspected input: {dict(counts)}')

    validation, reference_sources, reference_coverage = _reference_validation(
        Path.cwd().resolve(), protocol, records, assignments)
    for fid, frame in validation.frames.items():
        if fid in staged.frames:
            raise ValueError(f'train/validation identity overlap: {fid}')
        staged.add(frame)

    inputs = {'archive_sha256': file_digest(archive),
              'source_export_manifest_sha256': source_manifest_sha,
              'frame_index_sha256': index_sha,
              'protocol_sha256': file_digest(protocol/'protocol.json'),
              'parent_labels_sha256': file_digest(parent_labels),
              'parent_labels': str(parent_labels.resolve()),
              'source_export': str(source_export.resolve())}
    selection = {'train': sorted(source_frames), 'val': sorted(validation.frames), 'test': []}
    write_root = output/'inputs'
    write_root.mkdir(parents=True, exist_ok=True)
    save_jsonl(staged, write_root/'annotations.jsonl')
    write_json(write_root/'selection.json', selection)
    ref_list = [{'path': row['path'], 'sha256': row['label_sha256'],
                 'manifest_sha256': row['manifest_sha256']} for row in reference_sources
                if row['split'] == 'val' and row['verified']]
    write_json(write_root/'validation_sources.json', ref_list)
    training_entries = {fid: source_frames[fid] for fid in sorted(source_frames)}
    training_manifest = {'kind': 'explicit_user_confirmed_train_zip_manual_training_partition',
        'approver': 'user_confirmed_in_conversation', 'protocol_sha256': inputs['protocol_sha256'],
        'annotation_snapshot_sha256': file_digest(write_root/'annotations.jsonl'),
        'source_archive_sha256': inputs['archive_sha256'], 'source_frames': training_entries,
        'training_frame_ids': sorted(training_entries), 'training_frames': len(training_entries),
        'reviewer_count_claimed': 1,
        'note': 'User confirmed train.zip corrections and three empty frames as negatives; this explicit training attestation does not modify two-review or blind-reference eligibility.'}
    write_json(write_root/'human_training_manifest.json', training_manifest)
    write_json(write_root/'reference_manifest.json', {
        'split': 'val', 'blind_frozen_sources': ref_list,
        'source_reference_coverage': reference_coverage['val'],
        'selected_frames': len(validation.frames),
        'scorable_frames': sum(f.status in {'pos', 'negative'} for f in validation.frames.values()),
        'annotations_sha256': file_digest(write_root/'annotations.jsonl')})
    shutil.copyfile(archive, output/'train_source.zip')
    records_by_id = {row.frame_id: row for row in records}
    write_json(output/'import_report.json', {'created_at_utc': datetime.now(timezone.utc).isoformat(),
        'inputs': inputs, 'train_frames': len(source_frames), 'train_status_counts': dict(counts),
        'train_boxes': sum(r['instances'] for r in archive_rows),
        'train_groups': len({row['group_id'] for row in archive_rows}),
        'train_domains': dict(Counter(records_by_id[fid].domain for fid in source_frames)),
        'validation_frames': len(validation.frames),
        'validation_scorable_frames': sum(f.status in {'pos', 'negative'} for f in validation.frames.values()),
        'validation_ignore_frames': sum(f.status == 'ignore' for f in validation.frames.values()),
        'validation_sources': ref_list, 'selection_sha256': file_digest(write_root/'selection.json'),
        'annotations_sha256': file_digest(write_root/'annotations.jsonl'),
        'human_manifest_sha256': file_digest(write_root/'human_training_manifest.json'),
        'old_stale_flags_overridden_by_geometry': True,
        'old_audit_groups_in_training': 33,
        'audit_branch': 'independent auxiliary annotation assistant; excluded from legacy 49-frame convergence statistics'})
    input_manifest = {'inputs': inputs,
        'artifacts': {str(path.relative_to(output)): file_digest(path)
                      for path in sorted(output.rglob('*')) if path.is_file()
                      and path.name not in {'import_manifest.json'}},
        'state': 'imported'}
    write_json(output/'import_manifest.json', input_manifest)
    return input_manifest


def import_manual_correction_archives(*, corrections_config,
        protocol='outputs/protocol_v5', output=DEFAULT_MANUAL_1330_OUTPUT):
    """Import explicitly reviewed frames from multiple versioned AnyLabeling archives."""
    config_path = Path(corrections_config).resolve()
    config = json.loads(config_path.read_text())
    if config.get('kind') != 'user_confirmed_manual_correction_archives_v1':
        raise ValueError('unrecognized manual correction configuration')
    if config.get('all_frames_reviewed_by_user') is not True:
        raise ValueError('user attestation must cover every frame, including unchanged proposals')
    if config.get('unchanged_proposals_accepted_after_manual_review') is not True:
        raise ValueError('unchanged model proposals require explicit user acceptance after review')
    if config.get('empty_frames_confirmed_negative_by_user') is not True:
        raise ValueError('empty frames require explicit user confirmation as negative')
    protocol, output = Path(protocol), Path(output).resolve()
    protocol_sha = file_digest(protocol/'protocol.json')
    records, assignments, _ = load_protocol(protocol)
    records_by_id = {row.frame_id: row for row in records}
    sources = config.get('sources')
    if not isinstance(sources, list) or not sources:
        raise ValueError('correction config must list at least one archive/source-export pair')
    normalized_sources = []
    source_indexes = []
    for source in sources:
        archive = Path(source['archive']).resolve()
        source_export = Path(source['source_export']).resolve()
        manifest, index, by_filename, manifest_sha, index_sha = _load_frame_index(source_export)
        source_protocol_sha = (manifest.get('binding', {}).get('protocol_sha256')
                               or manifest.get('prediction_binding', {}).get('protocol_sha256'))
        if source_protocol_sha != protocol_sha:
            raise ValueError(f'source export belongs to a different frozen protocol: {source_export}')
        normalized_sources.append({'archive': str(archive), 'archive_sha256': file_digest(archive),
            'source_export': str(source_export), 'source_export_manifest_sha256': manifest_sha,
            'source_frame_index_sha256': index_sha, 'source_kind': manifest.get('kind'),
            'expected_frames': int(source['expected_frames'])})
        source_indexes.append((source, archive, source_export, manifest, index, by_filename))
    normalized_sources.sort(key=lambda row: row['archive'])
    normalized_config = {**config, 'sources': normalized_sources}
    input_binding = {'corrections_config_sha256': file_digest(config_path),
        'normalized_config_sha256': _sha(json.dumps(normalized_config, sort_keys=True,
                                                    separators=(',', ':')).encode()),
        'protocol_sha256': protocol_sha,
        'sources': [{key: row[key] for key in ('archive', 'archive_sha256', 'source_export',
            'source_export_manifest_sha256', 'source_frame_index_sha256', 'expected_frames')}
            for row in normalized_sources]}
    completion_path = output/'manual_import_manifest.json'
    if completion_path.is_file():
        prior = json.loads(completion_path.read_text())
        if prior.get('input_binding') != input_binding:
            raise ValueError('manual import workspace is bound to different sources/config; choose a new output')
        for relative, digest in prior.get('artifact_sha256', {}).items():
            path = output/relative
            if not path.is_file() or file_digest(path) != digest:
                raise ValueError(f'manual import artifact changed: {relative}')
        return prior
    if output.exists() and any(output.iterdir()):
        raise ValueError('manual import output is nonempty and has no matching completion manifest')

    all_frames = {}
    source_frame_rows = {}
    per_source_summary = []
    for source, archive, source_export, manifest, frame_index, by_filename in source_indexes:
        expected_frames = int(source['expected_frames'])
        archive_rows = []
        with zipfile.ZipFile(archive) as bundle:
            bad_member = bundle.testzip()
            if bad_member is not None:
                raise ValueError(f'correction archive CRC failed at {bad_member}')
            members = [item for item in bundle.infolist() if not item.is_dir()]
            if len(members) != expected_frames:
                raise ValueError(f'{archive.name}: expected {expected_frames} labels, found {len(members)}')
            names = set()
            for item in members:
                if PurePosixPath(item.filename).name != item.filename or Path(item.filename).suffix.lower() != '.json':
                    raise ValueError(f'archive contains unexpected member: {item.filename}')
                if item.filename in names:
                    raise ValueError(f'duplicate annotation in archive: {item.filename}')
                names.add(item.filename)
                document = json.loads(bundle.read(item))
                row = by_filename.get(item.filename)
                if row is None:
                    raise ValueError(f'annotation filename is absent from source index: {item.filename}')
                source_document_path = source_export/row['annotation']
                if not source_document_path.is_file():
                    raise FileNotFoundError(source_document_path)
                baseline_document = json.loads(source_document_path.read_text())
                baseline_sha = (row.get('baseline_json_sha256')
                    or row.get('baseline_annotation_sha256'))
                if baseline_sha and file_digest(source_document_path) != baseline_sha:
                    raise ValueError(f'source annotation changed since export: {row["frame_id"]}')
                metadata = document.get('pallet_export') or document.get('pallet_prediction') or {}
                baseline_metadata = (baseline_document.get('pallet_export')
                                     or baseline_document.get('pallet_prediction') or {})
                fid = row['frame_id']
                record = records_by_id.get(fid)
                from pallet.data.eligibility import exclusion_ids, require_eligible
                if fid in exclusion_ids():
                    raise ValueError(f'Frame retired from annotation dataset: {fid}')
                if record is not None:
                    require_eligible(record)
                if (metadata.get('frame_id') != fid or baseline_metadata.get('frame_id') != fid
                        or metadata.get('source_anchor_hash') != row.get('source_anchor_hash')
                        or baseline_metadata.get('source_anchor_hash') != row.get('source_anchor_hash')
                        or record is None or record.group_id != row.get('group_id')
                        or record.source_sha256 != row.get('source_anchor_hash')
                        or assignments.get(record.group_id) != 'train'
                        or row.get('split') != 'train'):
                    raise ValueError(f'frame identity or training-split mismatch: {item.filename}')
                width, height = row['size']
                source_image_path = source_export/row['image']
                if not source_image_path.is_file():
                    raise FileNotFoundError(f'paired source image is missing: {source_image_path}')
                image_digest = (row.get('view_sha256', {}).get('image')
                    or row.get('files', {}).get(row['image']))
                if image_digest and file_digest(source_image_path) != image_digest:
                    raise ValueError(f'paired source image hash mismatch: {fid}')
                with Image.open(source_image_path) as source_image:
                    if source_image.size != (width, height):
                        raise ValueError(f'paired source image dimensions mismatch: {fid}')
                if ((document.get('imageWidth'), document.get('imageHeight')) != (width, height)
                        or (baseline_document.get('imageWidth'), baseline_document.get('imageHeight')) != (width, height)
                        or document.get('imagePath') != baseline_document.get('imagePath')):
                    raise ValueError(f'image geometry/path changed in correction: {fid}')
                boxes = _decode_rectangles(document, width, height)
                status = 'pos' if boxes else 'negative'
                if fid in all_frames:
                    raise ValueError(f'frame appears in more than one user archive: {fid}')
                archive_sha = file_digest(archive)
                raw_geometry = lambda payload: [
                    {'label': shape.get('label'), 'shape_type': shape.get('shape_type'),
                     'points': shape.get('points')}
                    for shape in payload.get('shapes', [])]
                frame = FrameAnnotation(frame_id=fid, group_id=record.group_id,
                    image=str(row['image']), width=width, height=height, status=status,
                    boxes=boxes, scene=SceneAttributes(domain=row.get('domain', 'unknown')),
                    provenance=[Provenance(source='human', actor='user_confirmed_archive_import',
                        note=f'user-reviewed correction; archive={archive.name}; sha256={archive_sha}')],
                    split='train', domain=row.get('domain', 'unknown'),
                    source_anchor_hash=record.source_sha256)
                frame.validate()
                all_frames[fid] = frame
                entry = {'frame_id': fid, 'group_id': record.group_id,
                    'source_anchor_hash': record.source_sha256, 'split': 'train',
                    'width': width, 'height': height, 'domain': frame.domain,
                    'status': status, 'instances': len(boxes),
                    'annotation_digest': annotation_digest(frame),
                    'archive': str(archive), 'archive_sha256': archive_sha,
                    'source_export': str(source_export),
                    'source_export_manifest_sha256': file_digest(
                        source_export/('manifest.json' if (source_export/'manifest.json').is_file()
                                       else 'package_manifest.json')),
                    'source_json_sha256': _sha(bundle.read(item)),
                    'baseline_source_json_sha256': file_digest(source_document_path),
                    'source_proposal_status': baseline_metadata.get('status',
                        baseline_metadata.get('source_status')),
                    'geometry_unchanged_from_proposal':
                        raw_geometry(document) == raw_geometry(baseline_document)}
                source_frame_rows[fid] = entry
                archive_rows.append(entry)
        if len(archive_rows) != expected_frames:
            raise ValueError(f'{archive.name}: incomplete label import')
        per_source_summary.append({'archive': str(archive), 'archive_sha256': file_digest(archive),
            'frames': len(archive_rows), 'status_counts': dict(Counter(r['status'] for r in archive_rows)),
            'boxes': sum(r['instances'] for r in archive_rows),
            'geometry_unchanged': sum(r['geometry_unchanged_from_proposal'] for r in archive_rows)})
    counts = Counter(frame.status for frame in all_frames.values())
    boxes_total = sum(len(frame.boxes) for frame in all_frames.values())
    expected = config.get('expected_total') or {}
    actual = {'frames': len(all_frames), 'positive_frames': counts['pos'],
              'negative_frames': counts['negative'], 'boxes': boxes_total,
              'groups': len({frame.group_id for frame in all_frames.values()})}
    if any(actual.get(key) != value for key, value in expected.items()):
        raise ValueError(f'manual correction totals differ from attested config: {actual}')

    inputs = output/'inputs'
    inputs.mkdir(parents=True, exist_ok=True)
    save_jsonl(AnnotationSet(all_frames.values()), inputs/'manual_annotations.jsonl')
    write_json(inputs/'manual_source_frames.json', source_frame_rows)
    shutil.copy2(config_path, inputs/'corrections_config.json')
    archive_copy_dir = inputs/'source_archives'
    archive_copy_dir.mkdir(parents=True, exist_ok=True)
    for _, archive, *_ in source_indexes:
        target = archive_copy_dir/archive.name
        if target.exists() and file_digest(target) != file_digest(archive):
            raise ValueError(f'source archive copy collision: {target.name}')
        if not target.exists():
            shutil.copy2(archive, target)
    source_archive_digest = _sha(json.dumps([
        {'archive': row['archive'], 'sha256': row['archive_sha256']}
        for row in input_binding['sources']], sort_keys=True, separators=(',', ':')).encode())
    import_manifest = {'kind': 'multi_archive_user_confirmed_manual_labels',
        'state': 'imported', 'input_binding': input_binding,
        'source_archive_set_sha256': source_archive_digest,
        'protocol_sha256': protocol_sha, 'frame_count': len(all_frames),
        'status_counts': dict(counts), 'box_count': boxes_total,
        'group_count': actual['groups'], 'all_frames_reviewed_by_user': True,
        'empty_frames_confirmed_negative_by_user': True,
        'reviewer_count_claimed': 1, 'sources': per_source_summary,
        'artifact_sha256': {str(path.relative_to(output)): file_digest(path)
            for path in sorted(output.rglob('*')) if path.is_file()
            and path.name != 'manual_import_manifest.json'}}
    write_json(output/'manual_import_manifest.json', import_manifest)
    return import_manifest


def validate_human_training_manifest(manifest_path, manifest, annotations, protocol_dir):
    path = Path(manifest_path)
    kind = manifest.get('kind')
    auxiliary = kind == AUXILIARY_TRAIN_KIND and is_auxiliary_manifest(manifest)
    if not auxiliary and kind not in {'explicit_user_confirmed_manual_training_labels',
                                      'explicit_user_confirmed_train_zip_manual_training_partition'}:
        raise ValueError('unrecognized manual training attestation')
    protocol_hash = file_digest(Path(protocol_dir)/'protocol.json')
    if manifest.get('protocol_sha256') != protocol_hash:
        raise ValueError('manual training manifest belongs to another frozen protocol')
    if manifest.get('annotation_snapshot_sha256') != file_digest(path.parent/'annotations.jsonl'):
        raise ValueError('manual training labels changed after attestation')
    records, assignments, _ = load_protocol(protocol_dir)
    by_id = {row.frame_id: row for row in records}
    entries = manifest.get('source_frames') or {}
    if sorted(entries) != manifest.get('training_frame_ids') or len(entries) != manifest.get('training_frames'):
        raise ValueError('manual training frame selection is malformed')
    for fid, entry in entries.items():
        record, frame = by_id.get(fid), annotations.frames.get(fid)
        if record is not None:
            from pallet.data.eligibility import require_eligible
            require_eligible(record)
        pure_manual = (frame is not None and len(frame.provenance) == 1
            and frame.provenance[0].source == 'human'
            and frame.provenance[0].actor == 'user_confirmed_archive_import'
            and frame.scene == SceneAttributes(domain=frame.domain))
        expected_split = assignments.get(record.group_id) if record is not None else None
        if (record is None or frame is None
                or (not auxiliary and expected_split != 'train')
                or frame.split != expected_split or entry.get('split') != expected_split
                or frame.group_id != record.group_id or entry.get('group_id') != record.group_id
                or frame.source_anchor_hash != record.source_sha256
                or entry.get('source_anchor_hash') != record.source_sha256
                or frame.status not in {'pos', 'negative'}
                or (frame.status == 'pos') != bool(frame.boxes)
                or frame.ignore_regions
                or ((auxiliary or kind == 'explicit_user_confirmed_train_zip_manual_training_partition')
                    and not pure_manual)
                or annotation_digest(frame) != entry.get('annotation_digest')):
            raise ValueError(f'manual training attestation identity/label mismatch: {fid}')
    for frame in annotations.frames.values():
        if not auxiliary and frame.split in {'val', 'test'} and frame.provenance and any(
                p.source == 'human' for p in frame.provenance):
            raise ValueError('manual training snapshot may not relabel validation/test frames')
    return frozenset(entries)


def _manual_source_entry(frame, record):
    return {'group_id': frame.group_id, 'source_anchor_hash': frame.source_anchor_hash,
        'split': frame.split, 'width': frame.width, 'height': frame.height,
        'status': frame.status, 'instances': len(frame.boxes),
        'annotation_digest': annotation_digest(frame), 'domain': record.domain}


def _choose_group_holdout(frames, records_by_id, *, seed, fraction,
                          allow_train_only_domains=False):
    """Choose a deterministic, domain-stratified holdout without splitting groups."""
    by_domain = {}
    by_group = {}
    for frame in frames:
        record = records_by_id.get(frame.frame_id)
        if record is None:
            raise ValueError(f'manual frame is absent from frozen source records: {frame.frame_id}')
        if record.group_id != frame.group_id or record.source_sha256 != frame.source_anchor_hash:
            raise ValueError(f'manual frame source identity mismatch: {frame.frame_id}')
        by_group.setdefault(frame.group_id, []).append(frame)
    for group_id, group_frames in by_group.items():
        domains = {records_by_id[frame.frame_id].domain for frame in group_frames}
        if len(domains) != 1:
            raise ValueError(f'acquisition group spans configuration domains: {group_id}')
        domain = next(iter(domains))
        by_domain.setdefault(domain, {})[group_id] = group_frames

    selected_groups = set()
    domain_counts = {}
    for domain in sorted(by_domain):
        groups = by_domain[domain]
        total = sum(len(rows) for rows in groups.values())
        negative_total = sum(frame.status == 'negative'
                             for rows in groups.values() for frame in rows)
        target = max(1, int(math.floor(total * fraction + 0.5)))
        negative_target = int(math.floor(negative_total * fraction + 0.5))
        order = sorted(groups, key=lambda group_id: hashlib.sha256(
            f'{seed}|{domain}|{group_id}'.encode()).hexdigest())
        # State keys carry both total validation frames and negative frames so
        # negative examples can be retained in both partitions without splitting
        # acquisition groups.
        paths = {(0, 0): ()}
        for group_id in order:
            group_frames = groups[group_id]
            group_size = len(group_frames)
            group_negatives = sum(frame.status == 'negative' for frame in group_frames)
            for (subtotal, negative_count), chosen in list(paths.items())[::-1]:
                state = (subtotal + group_size, negative_count + group_negatives)
                if state[0] <= total - 1 and state not in paths:
                    paths[state] = (*chosen, group_id)
        negative_groups = sum(any(frame.status == 'negative' for frame in rows)
                              for rows in groups.values())
        available = []
        for (count, negative_count), chosen in paths.items():
            positive_count = count - negative_count
            train_positive = (total - count) - (negative_total - negative_count)
            if positive_count <= 0 or train_positive <= 0:
                continue
            if negative_total and negative_groups >= 2 and not 0 < negative_count < negative_total:
                continue
            if negative_total and negative_groups < 2 and negative_count == negative_total:
                continue
            available.append((count, negative_count, chosen))
        if not available:
            if not allow_train_only_domains:
                raise ValueError(f'cannot create a positive group-held-out manual validation set in {domain}')
            chosen_total, chosen_negatives, chosen_groups = 0, 0, ()
        else:
            chosen_total, chosen_negatives, chosen_groups = min(available,
                key=lambda row: (abs(row[0]-target), abs(row[1]-negative_target),
                                 row[0] > target, row[1] > negative_target,
                                 row[0], row[1], row[2]))
        selected_groups.update(chosen_groups)
        domain_counts[domain] = {'total_frames': total, 'target_frames': target,
            'negative_frames': negative_total, 'target_validation_negatives': negative_target,
            'negative_groups': negative_groups,
            'negative_stratification_feasible': negative_groups >= 2,
            'validation_frames': chosen_total, 'validation_negatives': chosen_negatives,
            'training_frames': total-chosen_total,
            'training_negatives': negative_total-chosen_negatives,
            'validation_groups': len(chosen_groups),
            'training_groups': len(groups)-len(chosen_groups)}
        if not available:
            domain_counts[domain]['validation_unavailable_reason'] = 'No positive group-disjoint holdout; all reviewed groups retained in auxiliary training.'
    selected = sorted(frame.frame_id for frame in frames if frame.group_id in selected_groups)
    return selected, selected_groups, domain_counts


def create_manual_validation_partition(*, source_output=DEFAULT_OUTPUT,
        output=DEFAULT_MANUAL_OUTPUT, protocol='outputs/protocol_v5',
        seed=42, validation_fraction=0.15):
    """Freeze group-disjoint training/validation using only confirmed human labels."""
    source_output, output, protocol = map(Path, (source_output, output, protocol))
    if not 0.05 <= validation_fraction <= 0.25:
        raise ValueError('manual validation fraction must be between 5% and 25%')
    multi_archive_manifest_path = source_output/'manual_import_manifest.json'
    if multi_archive_manifest_path.is_file():
        source_manifest = json.loads(multi_archive_manifest_path.read_text())
        source_annotations_path = source_output/'inputs/manual_annotations.jsonl'
        source_training_manifest_path = source_output/'inputs/manual_source_frames.json'
        source_annotations = load_jsonl(source_annotations_path)
        source_training_manifest = json.loads(source_training_manifest_path.read_text())
        manual_ids = set(source_manifest.get('source_frames', [])) or set(source_training_manifest)
        archive_sha = source_manifest['source_archive_set_sha256']
        source_archives = source_manifest['sources']
        source_import_sha = file_digest(multi_archive_manifest_path)
    else:
        source_annotations_path = source_output/'inputs/annotations.jsonl'
        source_training_manifest_path = source_output/'inputs/human_training_manifest.json'
        source_manifest = json.loads((source_output/'import_manifest.json').read_text())
        source_annotations = load_jsonl(source_annotations_path)
        source_training_manifest = json.loads(source_training_manifest_path.read_text())
        manual_ids = set(validate_human_training_manifest(source_training_manifest_path,
            source_training_manifest, source_annotations, protocol))
        archive_sha = source_manifest['inputs']['archive_sha256']
        if archive_sha != source_training_manifest['source_archive_sha256']:
            raise ValueError('manual labels are no longer bound to the user archive')
        source_archives = [{'archive': source_manifest['inputs'].get('archive', 'train.zip'),
                            'archive_sha256': archive_sha}]
        source_import_sha = file_digest(source_output/'import_manifest.json')
    if len(manual_ids) != len(source_annotations.frames):
        raise ValueError('manual import manifest does not enumerate its exact annotation snapshot')
    archive_note = f'user-corrected labels; archive-set sha256={archive_sha}'
    manual_frames = [replace(source_annotations.frames[fid],
        scene=SceneAttributes(domain=source_annotations.frames[fid].domain),
        provenance=[Provenance(source='human', actor='user_confirmed_archive_import',
                               note=archive_note)]) for fid in sorted(manual_ids)]
    if not manual_frames or any(
            len(frame.provenance) != 1 or frame.provenance[0].source != 'human'
            or frame.provenance[0].actor != 'user_confirmed_archive_import'
            for frame in manual_frames):
        raise ValueError('manual snapshot contains labels outside the confirmed correction archives')
    records, assignments, _ = load_protocol(protocol)
    records_by_id = {row.frame_id: row for row in records}
    auxiliary = (source_manifest.get('scope') == AUXILIARY_SCOPE
                 and source_manifest.get('original_splits_preserved') is True
                 and source_manifest.get('eligible_for_research_evaluation') is False)
    for frame in manual_frames:
        source_split = assignments.get(frame.group_id)
        if frame.split != source_split or (not auxiliary and source_split != 'train'):
            raise ValueError(f'manual assistant source frame is outside the frozen train split: {frame.frame_id}')
    validation_ids, validation_groups, domain_counts = _choose_group_holdout(
        manual_frames, records_by_id, seed=seed, fraction=validation_fraction,
        allow_train_only_domains=auxiliary)
    training_ids = sorted(manual_ids-set(validation_ids))
    if (set(training_ids) & set(validation_ids)
            or len(training_ids)+len(validation_ids) != len(manual_frames)):
        raise ValueError('manual holdout does not partition all corrected frames')
    train_groups = {source_annotations.frames[fid].group_id for fid in training_ids}
    val_groups = {source_annotations.frames[fid].group_id for fid in validation_ids}
    if train_groups & val_groups:
        raise ValueError('manual validation partition splits an acquisition group')
    if not any(source_annotations.frames[fid].boxes for fid in training_ids) or not any(
            source_annotations.frames[fid].boxes for fid in validation_ids):
        raise ValueError('manual training and validation both require positive pallet examples')
    for domain, summary in domain_counts.items():
        if (summary['negative_frames'] and summary['negative_stratification_feasible']
                and summary['validation_frames'] and summary['validation_negatives'] == 0):
            raise ValueError(f'manual validation has no negative frame in domain {domain}')
        if summary['negative_frames'] and summary['training_negatives'] == 0:
            raise ValueError(f'manual training has no negative frame in domain {domain}')

    write_root = output/'inputs'
    labels_path = write_root/'annotations.jsonl'
    if output.exists() and (output/'manual_partition.json').exists():
        partition = json.loads((output/'manual_partition.json').read_text())
        if (partition.get('source_archive_sha256') != archive_sha
                or partition.get('source_import_manifest_sha256') != source_import_sha
                or partition.get('protocol_sha256') != file_digest(protocol/'protocol.json')
                or partition.get('seed') != seed
                or partition.get('validation_fraction') != validation_fraction):
            raise ValueError('existing manual partition is bound to different inputs/configuration')
        artifacts = partition.get('artifact_sha256', {})
        for name, digest in artifacts.items():
            path = output/name
            if not path.is_file() or file_digest(path) != digest:
                raise ValueError(f'manual partition artifact changed: {name}')
        return partition
    if output.exists() and any(output.iterdir()) and not multi_archive_manifest_path.is_file():
        raise ValueError('manual validation output is partial/unbound; choose a fresh output directory')
    write_root.mkdir(parents=True, exist_ok=True)
    manual_snapshot = AnnotationSet(manual_frames)
    save_jsonl(manual_snapshot, labels_path)
    train_entries = {fid: _manual_source_entry(manual_snapshot.frames[fid], records_by_id[fid])
                     for fid in training_ids}
    val_entries = {fid: _manual_source_entry(manual_snapshot.frames[fid], records_by_id[fid])
                   for fid in validation_ids}
    source_frames = source_training_manifest
    for entries in (train_entries, val_entries):
        for fid, entry in entries.items():
            original = source_frames[fid]
            for key in ('source_json_sha256', 'baseline_source_json_sha256',
                        'source_export_manifest_sha256', 'archive_sha256', 'archive'):
                if key in original:
                    entry[key] = original[key]
    protocol_sha = file_digest(protocol/'protocol.json')
    training_manifest = {'kind': 'explicit_user_confirmed_manual_training_labels',
        'approver': 'user_confirmed_in_conversation', 'protocol_sha256': protocol_sha,
        'annotation_snapshot_sha256': file_digest(labels_path),
        'source_archive_sha256': archive_sha, 'source_frames': train_entries,
        'source_archives': source_archives,
        'training_frame_ids': training_ids, 'training_frames': len(training_ids),
        'reviewer_count_claimed': 1,
        'note': 'Only explicitly user-confirmed correction archives; group-disjoint manual validation frames are excluded.'}
    validation_manifest = {'kind': 'explicit_user_confirmed_manual_validation_holdout',
        'approver': 'user_confirmed_in_conversation', 'protocol_sha256': protocol_sha,
        'annotation_snapshot_sha256': file_digest(labels_path),
        'source_archive_sha256': archive_sha, 'source_frames': val_entries,
        'source_archives': source_archives,
        'validation_frame_ids': validation_ids, 'validation_frames': len(validation_ids),
        'reviewer_count_claimed': 1,
        'note': f'Held out by acquisition group from {len(manual_frames)} user-corrected frames; not an independent blind reference.'}
    if auxiliary:
        common = {'scope': AUXILIARY_SCOPE, 'original_splits_preserved': True,
                  'eligible_for_research_evaluation': False}
        training_manifest.update(common, kind=AUXILIARY_TRAIN_KIND)
        validation_manifest.update(common, kind=AUXILIARY_VAL_KIND)
    selection = {'train': training_ids, 'val': validation_ids, 'test': []}
    write_json(write_root/'human_training_manifest.json', training_manifest)
    write_json(write_root/'human_validation_manifest.json', validation_manifest)
    write_json(write_root/'selection.json', selection)
    partition = {'kind': 'manual_archives_group_disjoint_assistant_validation',
        'seed': seed, 'validation_fraction': validation_fraction,
        'protocol_sha256': protocol_sha, 'source_archive_sha256': archive_sha,
        'source_archives': source_archives,
        'source_import_manifest_sha256': source_import_sha,
        'source_human_manifest_sha256': file_digest(source_training_manifest_path),
        'manual_annotations_sha256': file_digest(labels_path),
        'expected_manual_frames': len(manual_frames),
        'all_manual_frame_ids': sorted(manual_ids), 'train_frame_ids': training_ids,
        'validation_frame_ids': validation_ids,
        'train_groups': sorted(train_groups), 'validation_groups': sorted(val_groups),
        'domain_counts': domain_counts,
        'status_counts': {'train': dict(Counter(source_annotations.frames[fid].status for fid in training_ids)),
                          'val': dict(Counter(source_annotations.frames[fid].status for fid in validation_ids))},
        'positive_boxes': {'train': sum(len(source_annotations.frames[fid].boxes) for fid in training_ids),
                           'val': sum(len(source_annotations.frames[fid].boxes) for fid in validation_ids)},
        'test_or_external_labels_used': auxiliary}
    if auxiliary:
        partition.update(scope=AUXILIARY_SCOPE, original_splits_preserved=True,
                         eligible_for_research_evaluation=False)
    artifact_paths = [labels_path, write_root/'human_training_manifest.json',
                      write_root/'human_validation_manifest.json', write_root/'selection.json']
    partition['artifact_sha256'] = {str(path.relative_to(output)): file_digest(path)
                                    for path in artifact_paths}
    write_json(output/'manual_partition.json', partition)
    return partition


def validate_human_validation_manifest(manifest_path, manifest, annotations, protocol_dir,
                                       training_ids):
    path = Path(manifest_path)
    auxiliary = manifest.get('kind') == AUXILIARY_VAL_KIND and is_auxiliary_manifest(manifest)
    if not auxiliary and manifest.get('kind') != 'explicit_user_confirmed_manual_validation_holdout':
        raise ValueError('unrecognized manual validation attestation')
    if manifest.get('annotation_snapshot_sha256') != file_digest(path.parent/'annotations.jsonl'):
        raise ValueError('manual validation labels changed after attestation')
    if manifest.get('protocol_sha256') != file_digest(Path(protocol_dir)/'protocol.json'):
        raise ValueError('manual validation manifest belongs to another frozen protocol')
    records, assignments, _ = load_protocol(protocol_dir)
    by_id = {row.frame_id: row for row in records}
    entries = manifest.get('source_frames') or {}
    ids = manifest.get('validation_frame_ids')
    if (not isinstance(ids, list) or sorted(entries) != ids
            or len(entries) != manifest.get('validation_frames')
            or set(entries) & set(training_ids)):
        raise ValueError('manual validation selection is malformed or overlaps training')
    for fid, entry in entries.items():
        record, frame = by_id.get(fid), annotations.frames.get(fid)
        if record is not None:
            from pallet.data.eligibility import require_eligible
            require_eligible(record)
        human_origin = (frame is not None and len(frame.provenance) == 1
            and frame.provenance[0].source == 'human'
            and frame.provenance[0].actor == 'user_confirmed_archive_import'
            and frame.scene == SceneAttributes(domain=frame.domain))
        expected_split = assignments.get(record.group_id) if record is not None else None
        if (record is None or frame is None or not human_origin
                or (not auxiliary and expected_split != 'train')
                or frame.split != expected_split or entry.get('split') != expected_split
                or frame.group_id != record.group_id or entry.get('group_id') != record.group_id
                or frame.source_anchor_hash != record.source_sha256
                or entry.get('source_anchor_hash') != record.source_sha256
                or frame.status not in {'pos', 'negative'}
                or (frame.status == 'pos') != bool(frame.boxes)
                or frame.ignore_regions
                or annotation_digest(frame) != entry.get('annotation_digest')):
            raise ValueError(f'manual validation identity/label mismatch: {fid}')
    return frozenset(entries)


def _validated_manual_partition(output, protocol):
    output, protocol = Path(output), Path(protocol)
    labels_path = output/'inputs/annotations.jsonl'
    training_path = output/'inputs/human_training_manifest.json'
    validation_path = output/'inputs/human_validation_manifest.json'
    annotations = load_jsonl(labels_path)
    training_manifest = json.loads(training_path.read_text())
    validation_manifest = json.loads(validation_path.read_text())
    train_ids = validate_human_training_manifest(training_path, training_manifest,
                                                  annotations, protocol)
    val_ids = validate_human_validation_manifest(validation_path, validation_manifest,
                                                  annotations, protocol, train_ids)
    selection = json.loads((output/'inputs/selection.json').read_text())
    partition = json.loads((output/'manual_partition.json').read_text())
    auxiliary = is_auxiliary_manifest(training_manifest)
    if auxiliary != is_auxiliary_manifest(validation_manifest):
        raise ValueError('manual training/validation scopes do not match')
    if auxiliary and (partition.get('scope') != AUXILIARY_SCOPE
            or partition.get('original_splits_preserved') is not True
            or partition.get('eligible_for_research_evaluation') is not False):
        raise ValueError('cross-split manual labels require an isolated auxiliary partition')
    if (set(selection.get('train', [])) != train_ids or set(selection.get('val', [])) != val_ids
            or selection.get('test') or train_ids | val_ids != set(partition.get('all_manual_frame_ids', []))
            or train_ids | val_ids != set(annotations.frames)):
        raise ValueError('manual partition files do not describe the exact user-corrected archive')
    if partition.get('manual_annotations_sha256') != file_digest(labels_path):
        raise ValueError('manual partition annotation snapshot hash mismatch')
    if partition.get('protocol_sha256') != file_digest(protocol/'protocol.json'):
        raise ValueError('manual partition belongs to another frozen protocol')
    for name, digest in partition.get('artifact_sha256', {}).items():
        path = output/name
        if not path.is_file() or file_digest(path) != digest:
            raise ValueError(f'manual partition artifact changed: {name}')
    if (partition.get('source_archive_sha256') != training_manifest.get('source_archive_sha256')
            or partition.get('source_archive_sha256') != validation_manifest.get('source_archive_sha256')):
        raise ValueError('manual partition manifests refer to different correction archives')
    expected_frames = partition.get('expected_manual_frames',
                                    len(partition.get('all_manual_frame_ids', [])))
    if (len(annotations.frames) != expected_frames
            or partition.get('test_or_external_labels_used') is not auxiliary
            or any(len(frame.provenance) != 1 or frame.provenance[0].source != 'human'
                   or frame.provenance[0].actor != 'user_confirmed_archive_import'
                   or frame.scene != SceneAttributes(domain=frame.domain)
                   for frame in annotations.frames.values())):
        raise ValueError('manual validation branch contains unexpected labels or provenance')
    if (partition.get('source_archives') != training_manifest.get('source_archives')
            or partition.get('source_archives') != validation_manifest.get('source_archives')):
        raise ValueError('manual train and validation manifests refer to different correction archives')
    imported_manifest_path = output/'manual_import_manifest.json'
    if imported_manifest_path.is_file():
        imported = json.loads(imported_manifest_path.read_text())
        if (imported.get('source_archive_set_sha256') != partition.get('source_archive_sha256')
                or imported.get('frame_count') != expected_frames
                or imported.get('protocol_sha256') != partition.get('protocol_sha256')):
            raise ValueError('manual partition differs from its multi-archive import manifest')
        for name, digest in imported.get('artifact_sha256', {}).items():
            path = output/name
            if not path.is_file() or file_digest(path) != digest:
                raise ValueError(f'manual import artifact changed: {name}')
    groups = {fid: annotations.frames[fid].group_id for fid in annotations.frames}
    if {groups[fid] for fid in train_ids} & {groups[fid] for fid in val_ids}:
        raise ValueError('manual training and validation share an acquisition group')
    return annotations, train_ids, val_ids, selection, partition


def _validated_stage(output, protocol, labels, subset, training_manifest):
    output, protocol = Path(output), Path(protocol)
    annotations = load_jsonl(labels)
    human = json.loads(Path(training_manifest).read_text())
    ids = validate_human_training_manifest(training_manifest, human, annotations, protocol)
    selection = json.loads(Path(subset).read_text())
    if set(selection.get('train', [])) != ids or selection.get('test'):
        raise ValueError('training subset is not exactly the manually attested source-training set')
    if len(selection.get('val', [])) != 596:
        raise ValueError('training subset must bind all 596 independent validation-reference frames')
    for fid in selection['val']:
        frame = annotations.frames.get(fid)
        if frame is None or frame.split != 'val' or not is_resolved(frame, require_blind=True):
            raise ValueError(f'validation frame is not an independent frozen reference: {fid}')
    train_args = output/'training_command.json'
    return annotations, human, ids, selection, train_args


def train_assistant(*, output=DEFAULT_OUTPUT, protocol='outputs/protocol_v5',
                    root=DEFAULT_ROOT, device=RTX3090_UUID, epochs=300):
    output, protocol, root = Path(output), Path(protocol), Path(root)
    if (output/'superseded.json').is_file() and not (output/'inputs/human_validation_manifest.json').is_file():
        raise ValueError('this assistant stage was superseded; use the manual-only validation branch')
    labels = output/'inputs/annotations.jsonl'
    human_manifest_path = output/'inputs/human_training_manifest.json'
    subset = output/'inputs/selection.json'
    training = output/'training'
    annotations, human, ids, selection, command_path = _validated_stage(
        output, protocol, labels, subset, human_manifest_path)
    if human['source_archive_sha256'] != json.loads(
            (output/'import_manifest.json').read_text())['inputs']['archive_sha256']:
        raise ValueError('manual labels no longer match the imported ZIP binding')
    if Path(device).name in {'', '.'}:
        raise ValueError('device UUID is required')
    device = pinned_cuda_metadata(device)
    if epochs < 10 or epochs > 300:
        raise ValueError('assistant training supports 10..300 epochs with early stopping')
    checkpoint_seed = Path('yolo26s.pt').resolve()
    if not checkpoint_seed.is_file():
        raise FileNotFoundError('official yolo26s.pt initialization weight is unavailable')
    config = {**MODEL_CONFIG, 'epochs': epochs, 'device_uuid': device['uuid'],
        'device_name': device['name'], 'initial_weight_path': str(checkpoint_seed),
        'initial_weight_sha256': file_digest(checkpoint_seed),
        'annotations_sha256': file_digest(labels),
        'human_manifest_sha256': file_digest(human_manifest_path),
        'selection_sha256': file_digest(subset),
        'protocol_sha256': file_digest(protocol/'protocol.json'),
        'cache_index_sha256': file_digest(Path(active_policy()[0].get('cache_index', 'outputs/cache_v5/sealed_index.json')))}
    command_path.parent.mkdir(parents=True, exist_ok=True)
    if command_path.exists():
        old = json.loads(command_path.read_text())
        if old['config'] != config:
            raise ValueError('training workspace is bound to a different source/config; use a new version')
    else:
        if training.exists() and any(training.iterdir()):
            raise ValueError('unbound training output exists; refusing to resume')
        write_json(command_path, {'config': config, 'state': 'ready',
                                  'command': None, 'log': 'training.log'})
    if (training/'completed.json').exists():
        completion = json.loads((training/'completed.json').read_text())
        if file_digest(training/'best.pt') != completion['best_checkpoint_sha256']:
            raise ValueError('completed assistant checkpoint hash mismatch')
        return {'state': 'complete', 'checkpoint': str(training/'best.pt'),
                'completed': completion}

    args = [sys.executable, '-m', 'pallet.cli', 'train', '--root', str(root),
        '--protocol', str(protocol), '--annotations', str(labels),
        '--human-annotations-manifest', str(human_manifest_path),
        '--subset', str(subset), '--output', str(training), '--family', 'yolo26',
        '--recipe', 'official_research_constrained', '--pretrained', str(checkpoint_seed),
        '--seed', '42', '--epochs', str(epochs), '--batch-size', '4',
        '--effective-batch', '16', '--size', '640', '--device', device['uuid'],
        '--no-p2', '--no-fusion', '--no-edge']
    write_json(command_path, {'config': config, 'state': 'running', 'command': args,
                              'started_at_utc': datetime.now(timezone.utc).isoformat(),
                              'log': str(output/'training.log')})
    training.mkdir(parents=True, exist_ok=True)
    log = output/'training.log'
    with log.open('a', encoding='utf-8') as stream:
        process = subprocess.Popen(args, stdout=stream, stderr=subprocess.STDOUT,
                                   cwd=Path.cwd())
        write_json(output/'training_process.json', {'pid': process.pid, 'command': args,
            'device_uuid': device['uuid'], 'started_at_utc': datetime.now(timezone.utc).isoformat()})
        result = process.wait()
    if result:
        write_json(command_path, {'config': config, 'state': 'failed_resumable',
            'exit_code': result, 'command': args, 'log': str(log)})
        raise RuntimeError(f'training exited {result}; resume with the same command after inspecting {log}')
    completion = json.loads((training/'completed.json').read_text())
    best = training/'best.pt'
    if (file_digest(best) != completion['best_checkpoint_sha256']
            or completion['completed_epochs'] < 1):
        raise ValueError('trainer completion record/checkpoint hash failed verification')
    metrics = [json.loads(line) for line in (training/'metrics.jsonl').read_text().splitlines() if line]
    elapsed = _epoch_timing_estimate(metrics, epochs)
    write_json(output/'runtime_estimate.json', elapsed)
    write_json(command_path, {'config': config, 'state': 'complete', 'command': args,
        'completion_sha256': file_digest(training/'completed.json'),
        'checkpoint_sha256': file_digest(best), 'metrics_sha256': file_digest(training/'metrics.jsonl'),
        'completed_at_utc': datetime.now(timezone.utc).isoformat()})
    return {'state': 'complete', 'checkpoint': str(best), 'completed': completion,
            'runtime_estimate': elapsed}


def train_manual_validation_assistant(*, output=DEFAULT_MANUAL_OUTPUT,
        protocol='outputs/protocol_v5', root=DEFAULT_ROOT, device=RTX3090_UUID,
        epochs=300, batch_size=4, workers=0, validation_batch_size=1):
    """Train/select using only archive corrections, with a group-held-out manual split."""
    output, protocol, root = Path(output), Path(protocol), Path(root)
    annotations, train_ids, val_ids, selection, partition = _validated_manual_partition(
        output, protocol)
    labels = output/'inputs/annotations.jsonl'
    train_manifest = output/'inputs/human_training_manifest.json'
    val_manifest = output/'inputs/human_validation_manifest.json'
    subset = output/'inputs/selection.json'
    if Path(device).name in {'', '.'}:
        raise ValueError('device UUID is required')
    device_info = pinned_cuda_metadata(device)
    if epochs < 10 or epochs > 300:
        raise ValueError('assistant training supports 10..300 epochs with early stopping')
    if batch_size not in (1, 2, 4, 8, 16) or workers < 0 or validation_batch_size < 1:
        raise ValueError('batch size must divide effective batch16; invalid loader settings')
    checkpoint_seed = Path('yolo26s.pt').resolve()
    if not checkpoint_seed.is_file():
        raise FileNotFoundError('official yolo26s.pt initialization weight is unavailable')
    config = {**MODEL_CONFIG, 'epochs': epochs, 'batch_size': batch_size,
        'device_uuid': device_info['uuid'],
        'device_name': device_info['name'], 'initial_weight_path': str(checkpoint_seed),
        'initial_weight_sha256': file_digest(checkpoint_seed),
        'manual_annotations_sha256': file_digest(labels),
        'human_training_manifest_sha256': file_digest(train_manifest),
        'human_validation_manifest_sha256': file_digest(val_manifest),
        'manual_partition_sha256': file_digest(output/'manual_partition.json'),
        'selection_sha256': file_digest(subset),
        'protocol_sha256': file_digest(protocol/'protocol.json'),
        'cache_index_sha256': file_digest(Path(active_policy()[0].get('cache_index', 'outputs/cache_v5/sealed_index.json'))),
        'train_frames': len(train_ids), 'validation_frames': len(val_ids),
        'manual_frame_count': len(partition['all_manual_frame_ids']),
        'source_archive_set_sha256': partition['source_archive_sha256'],
        'selection_reference': 'user-confirmed held-out correction-archive annotations only'}
    if workers or validation_batch_size != 1:
        config.update(workers=workers, validation_batch_size=validation_batch_size,
                      loader_policy='spawn_prefetch2_epoch_reseed_v1')
    command_path = output/'training_command.json'
    training = output/'training'
    if command_path.exists():
        old = json.loads(command_path.read_text())
        if old['config'] != config:
            raise ValueError('manual training run is bound to a different source/config; use a new version')
    elif training.exists() and any(training.iterdir()):
        raise ValueError('unbound manual training output exists; refusing to resume')
    completion_path = training/'completed.json'
    best = training/'best.pt'
    if completion_path.exists():
        completion = json.loads(completion_path.read_text())
        if file_digest(best) != completion.get('best_checkpoint_sha256'):
            raise ValueError('completed manual assistant checkpoint hash mismatch')
        return {'state': 'complete', 'checkpoint': str(best), 'completed': completion}

    args = [sys.executable, '-m', 'pallet.cli', 'train', '--root', str(root),
        '--protocol', str(protocol), '--annotations', str(labels),
        '--human-annotations-manifest', str(train_manifest),
        '--human-validation-manifest', str(val_manifest),
        '--subset', str(subset), '--output', str(training), '--family', 'yolo26',
        '--recipe', 'official_research_constrained', '--pretrained', str(checkpoint_seed),
        '--seed', '42', '--epochs', str(epochs), '--batch-size', str(batch_size),
        '--effective-batch', '16', '--size', '640', '--device', device_info['uuid'],
        '--no-p2', '--no-fusion', '--no-edge']
    if workers or validation_batch_size != 1:
        args.extend(['--workers', str(workers), '--validation-batch-size',
                     str(validation_batch_size)])
    log = output/'training.log'
    training.mkdir(parents=True, exist_ok=True)
    write_json(command_path, {'config': config, 'state': 'running', 'command': args,
        'started_at_utc': datetime.now(timezone.utc).isoformat(), 'log': str(log)})
    with log.open('a', encoding='utf-8') as stream:
        process = subprocess.Popen(args, stdout=stream, stderr=subprocess.STDOUT,
                                   cwd=Path.cwd())
        write_json(output/'training_process.json', {'pid': process.pid, 'command': args,
            'device_uuid': device_info['uuid'],
            'started_at_utc': datetime.now(timezone.utc).isoformat()})
        result = process.wait()
    if result:
        write_json(command_path, {'config': config, 'state': 'failed_resumable',
            'exit_code': result, 'command': args, 'log': str(log)})
        raise RuntimeError(f'manual training exited {result}; inspect {log} and resume same run')
    completion = json.loads(completion_path.read_text())
    if file_digest(best) != completion['best_checkpoint_sha256']:
        raise ValueError('manual training completion/checkpoint hash mismatch')
    metrics = [json.loads(line) for line in (training/'metrics.jsonl').read_text().splitlines() if line]
    elapsed = _epoch_timing_estimate(metrics, epochs)
    write_json(output/'runtime_estimate.json', elapsed)
    write_json(command_path, {'config': config, 'state': 'complete', 'command': args,
        'completion_sha256': file_digest(completion_path),
        'checkpoint_sha256': file_digest(best), 'metrics_sha256': file_digest(training/'metrics.jsonl'),
        'completed_at_utc': datetime.now(timezone.utc).isoformat()})
    return {'state': 'complete', 'checkpoint': str(best), 'completed': completion,
            'runtime_estimate': elapsed}


def _epoch_timing_estimate(metrics, target_epochs):
    # The native trainer currently records epoch quality but no wall clock.
    # Use its process UTC interval and actual completed epochs when available.
    durations = []
    for row in metrics[:10]:
        value = row.get('epoch_seconds')
        if value is not None and math.isfinite(value) and value > 0:
            durations.append(value)
    if durations:
        median = float(np.median(durations))
        return {'timing_basis': 'first ten real training epochs', 'measured_epochs': len(durations),
                'median_seconds_per_epoch': median,
                'estimated_remaining_seconds': max(0, target_epochs-len(metrics))*median}
    return {'timing_basis': 'trainer does not record per-epoch wall time yet',
            'measured_epochs': len(metrics), 'estimated_remaining_seconds': None}


class _InferenceDataset(Dataset):
    def __init__(self, rows, normalization, size):
        self.rows, self.normalization, self.size = rows, normalization, size
    def __len__(self):
        return len(self.rows)
    def __getitem__(self, index):
        row = self.rows[index]
        data = load_frame(row)
        image, scale, padding = letterbox_float(apply_normalization(data, self.normalization), self.size)
        return image, SampleMeta(row.frame_id, data.shape[:2], scale, padding)


def _collate_inference(rows):
    return torch.stack([row[0] for row in rows]), [row[1] for row in rows]


def _eligible_validation(root, protocol, base_path):
    records, assignments, _ = load_protocol(protocol)
    references, coverage = collect_references(root, protocol=protocol)
    if coverage['val']['payload_conflicts'] or coverage['val']['status_conflicts']:
        raise ValueError('validation reference coverage has conflicts')
    labels = {}
    sources = []
    for reference in references:
        if reference['split'] != 'val' or not reference['verified']:
            continue
        sources.append({'path': reference['path'], 'sha256': reference['label_sha256'],
                        'manifest_sha256': reference['manifest_sha256']})
        labels.update(load_jsonl(root/reference['path']).frames)
    usable = [frame for frame in labels.values() if frame.status in {'pos', 'negative'}
              and is_resolved(frame, require_blind=True)]
    if len(labels) != 596 or len(usable) != 463:
        raise ValueError('frozen independent validation coverage no longer matches 596/463')
    return records, labels, usable, sources


def calibrate_threshold(*, output=DEFAULT_OUTPUT, protocol='outputs/protocol_v5',
                        root=DEFAULT_ROOT, device=RTX3090_UUID):
    output, protocol, root = Path(output), Path(protocol), Path(root).resolve()
    if (output/'superseded.json').is_file() and not (output/'inputs/human_validation_manifest.json').is_file():
        raise ValueError('this assistant stage was superseded because its old validation labels are untrusted')
    training = output/'training'
    best = training/'best.pt'
    completion_path = training/'completed.json'
    if not completion_path.is_file():
        raise ValueError('assistant training has not completed')
    completion = json.loads(completion_path.read_text())
    if file_digest(best) != completion['best_checkpoint_sha256']:
        raise ValueError('best assistant checkpoint differs from completed training')
    manual_validation = (output/'inputs/human_validation_manifest.json').is_file()
    if manual_validation:
        labels, _, val_ids, _, partition = _validated_manual_partition(output, protocol)
        records, assignments, _ = load_protocol(protocol)
        auxiliary = partition.get('scope') == AUXILIARY_SCOPE
        if not auxiliary and any(assignments.get(labels.frames[fid].group_id) != 'train' for fid in val_ids):
            raise ValueError('manual validation frame left the original source-train groups')
        val_frames = [labels.frames[fid] for fid in sorted(val_ids)]
        sources = [{'kind': ('user_confirmed_cross_split_annotation_assistant_validation'
                            if auxiliary else 'user_confirmed_train_zip_manual_validation'),
                    'annotation_sha256': file_digest(output/'inputs/annotations.jsonl'),
                    'validation_manifest_sha256': file_digest(
                        output/'inputs/human_validation_manifest.json'),
                    'partition_sha256': file_digest(output/'manual_partition.json'),
                    'source_archive_sha256': partition['source_archive_sha256']}]
    else:
        records, labels, val_frames, sources = _eligible_validation(Path.cwd().resolve(), protocol, None)
    rows = {row.frame_id: row for row in _attach_cache(records, 'outputs/cache_v5/sealed_index.json')}
    state = torch.load(best, map_location='cpu', weights_only=False)
    stats = NormalizationStats(**state['normalization'])
    model, config = load_detector_checkpoint(best)
    device_obj = resolve_device(device)
    model.eval().to(device_obj)
    observations = []
    timings = []
    for frame in val_frames:
        row = rows.get(frame.frame_id)
        if row is None or row.group_id != frame.group_id or row.source_sha256 != frame.source_anchor_hash:
            raise ValueError(f'validation identity mismatch during threshold calibration: {frame.frame_id}')
        started = time.perf_counter()
        raw = load_frame(row)
        image, scale, padding = letterbox_float(apply_normalization(raw, stats), config['size'])
        meta = SampleMeta(frame.frame_id, raw.shape[:2], scale, padding)
        boxes = predict_boxes(model, image[None].to(device_obj), meta, conf=min(CONFIDENCE_GRID),
                              size=config['size'])
        timings.append(time.perf_counter()-started)
        observations.append((frame, boxes))
    curve = []
    for threshold in CONFIDENCE_GRID:
        tp = fp = fn = 0
        for frame, boxes in observations:
            a, b, c = _count_matches(boxes, frame.boxes, threshold, frame.ignore_regions)
            tp += a; fp += b; fn += c
        curve.append({'confidence': threshold, 'tp': tp, 'fp': fp, 'fn': fn,
            'recall': tp/(tp+fn) if tp+fn else None,
            'precision': tp/(tp+fp) if tp+fp else None,
            'false_positives_per_frame': fp/len(observations)})
    viable = [row for row in curve if row['recall'] is not None and row['recall'] >= .95]
    selected = max((row['confidence'] for row in viable), default=CONFIDENCE_GRID[0])
    chosen = next(row for row in curve if row['confidence'] == selected)
    result = {'protocol_sha256': file_digest(protocol/'protocol.json'),
        'checkpoint_sha256': file_digest(best), 'reference_sources': sources,
        'validation_reference': ('user-confirmed held-out correction-archive annotations'
                                 if manual_validation else 'independently reviewed machine annotations'),
        'validation_reference_frames': (len(val_frames) if manual_validation else len(labels.frames)),
        'scored_validation_frames': len(observations),
        'scored_ground_truth_boxes': sum(len(f.boxes) for f in val_frames),
        'selection_rule': 'maximum tested confidence with one-to-one IoU>=0.5 recall >= 0.95; otherwise use 0.05',
        'threshold_grid': list(CONFIDENCE_GRID), 'curve': curve,
        'selected_confidence': selected, 'fallback_used': not bool(viable),
        'selected_validation_metrics': chosen,
        'inference_seconds_per_frame_median': float(np.median(timings)),
        'test_accessed': False}
    if manual_validation:
        result['validation_reference_frames'] = len(val_frames)
        result['scope'] = partition.get('scope', 'source_train_annotation_assistance')
        result['original_test_labels_used_for_assistance'] = auxiliary
        result['test_accessed'] = auxiliary and any(frame.split == 'test' for frame in val_frames)
        result['final_research_test_scored'] = False
        result['manual_validation_frame_ids_sha256'] = _sha(
            json.dumps(sorted(fid for fid in _validated_manual_partition(output, protocol)[2]),
                       separators=(',', ':')).encode())
    path = output/'confidence_threshold.json'
    if path.exists() and json.loads(path.read_text()).get('checkpoint_sha256') != result['checkpoint_sha256']:
        raise ValueError('threshold already bound to a different best checkpoint')
    write_json(path, result)
    return result


def _reviewed_external_exclusions(output, protocol):
    """Exclude checked original val/test frames without reading their labels for fitting."""
    path = Path(output)/'inputs/reviewed_external_exclusion.json'
    if not path.exists():
        return frozenset(), None
    manifest = json.loads(path.read_text())
    if manifest.get('protocol_sha256') != file_digest(Path(protocol)/'protocol.json'):
        raise ValueError('external reviewed exclusion belongs to another protocol')
    receipt = Path(output)/manifest['receipt_path']
    if file_digest(receipt) != manifest['receipt_sha256']:
        raise ValueError('external review receipt changed')
    records, assignments, _ = load_protocol(protocol)
    by_id = {r.frame_id:r for r in records}
    ids = manifest.get('frame_ids', [])
    if len(ids) != len(set(ids)) or any(fid not in by_id or assignments[by_id[fid].group_id] not in {'val','test'} for fid in ids):
        raise ValueError('external exclusion must contain unique original val/test IDs')
    if set(json.loads(receipt.read_text())['frame_ids']) != set(ids):
        raise ValueError('external review receipt frame IDs mismatch')
    return frozenset(ids), file_digest(path)


def predict_remaining(*, output=DEFAULT_OUTPUT, protocol='outputs/protocol_v5',
                      root=DEFAULT_ROOT, source_export=DEFAULT_SOURCE_EXPORT,
                      device=RTX3090_UUID, batch_size=4):
    output, protocol, root = Path(output), Path(protocol), Path(root).resolve()
    if (output/'superseded.json').is_file() and not (output/'inputs/human_validation_manifest.json').is_file():
        raise ValueError('refusing predictions from an assistant selected on untrusted original labels')
    source_export = Path(source_export)
    training = output/'training'; best = training/'best.pt'
    completion_path = training/'completed.json'
    if not completion_path.is_file():
        raise ValueError('assistant training has not completed')
    completion = json.loads(completion_path.read_text())
    if file_digest(best) != completion['best_checkpoint_sha256']:
        raise ValueError('assistant checkpoint hash mismatch')
    threshold_path = output/'confidence_threshold.json'
    if not threshold_path.is_file():
        raise ValueError('run validation confidence calibration before prediction')
    threshold = json.loads(threshold_path.read_text())
    if threshold['checkpoint_sha256'] != file_digest(best):
        raise ValueError('threshold is bound to a different checkpoint')
    source_manifest, frame_index, _, source_manifest_sha, index_sha = _load_frame_index(source_export)
    records, assignments, _ = load_protocol(protocol)
    from pallet.data.eligibility import eligible_records
    records = eligible_records(records)
    record_ids = {row.frame_id for row in records}
    if set(frame_index) != record_ids:
        raise ValueError('source export does not cover the complete frozen protocol')
    manual_validation = (output/'inputs/human_validation_manifest.json').is_file()
    if manual_validation:
        annotations, train_ids, validation_ids, selection, partition = _validated_manual_partition(
            output, protocol)
        manual_ids = set(train_ids) | set(validation_ids)
    else:
        annotations = load_jsonl(output/'inputs/annotations.jsonl')
        human = json.loads((output/'inputs/human_training_manifest.json').read_text())
        train_ids = validate_human_training_manifest(output/'inputs/human_training_manifest.json',
                                                     human, annotations, protocol)
        selection = json.loads((output/'inputs/selection.json').read_text())
        manual_ids = set(train_ids)
        partition = None
    external_ids, external_sha = _reviewed_external_exclusions(output, protocol)
    manual_ids = manual_ids | set(external_ids)
    selected = [row for row in records if row.frame_id in frame_index and row.frame_id not in manual_ids]
    selected.sort(key=lambda row: (assignments[row.group_id], row.frame_id))
    expected = Counter(assignments[row.group_id] for row in records
                       if row.frame_id in frame_index and row.frame_id not in manual_ids)
    selected_counts = Counter(assignments[row.group_id] for row in selected)
    if selected_counts != expected or len(selected) != sum(expected.values()):
        raise ValueError(f'remaining prediction selection changed: {dict(selected_counts)}')
    by_id = {row.frame_id: row for row in records}
    attached = {row.frame_id: row for row in _attach_cache(records, 'outputs/cache_v5/sealed_index.json')}
    prediction_root = output/'predictions'
    prediction_root.mkdir(parents=True, exist_ok=True)
    prediction_manifest_path = output/'prediction_manifest.json'
    device_info = device_metadata(device)
    train_config = json.loads((output/'training_command.json').read_text())['config']
    if device_info['uuid'] != train_config['device_uuid']:
        raise ValueError('prediction must use the UUID-pinned training GPU')
    binding = {'protocol_sha256': file_digest(protocol/'protocol.json'),
        'source_export_manifest_sha256': source_manifest_sha,
        'source_frame_index_sha256': index_sha, 'checkpoint_sha256': file_digest(best),
        'threshold_sha256': file_digest(threshold_path),
        'selection_sha256': _sha(json.dumps([r.frame_id for r in selected]).encode()),
        'training_subset_sha256': file_digest(output/'inputs/selection.json'),
        'manual_validation_manifest_sha256': (file_digest(
            output/'inputs/human_validation_manifest.json') if manual_validation else None),
        'manual_partition_sha256': (file_digest(output/'manual_partition.json') if manual_validation else None),
        'device_uuid': device_info['uuid']}
    if external_sha:
        binding['reviewed_external_exclusion_sha256'] = external_sha
    if prediction_manifest_path.exists():
        previous = json.loads(prediction_manifest_path.read_text())
        if previous['binding'] != binding:
            raise ValueError('existing predictions are bound to different sources/model; use a new output version')
    else:
        write_json(prediction_manifest_path, {'binding': binding, 'state': 'predicting',
            'expected_frames': len(selected), 'expected_by_split': dict(expected),
            'completed_frames': 0, 'errors': {}, 'started_at_utc': datetime.now(timezone.utc).isoformat()})
    state = json.loads(prediction_manifest_path.read_text())
    files = {r.frame_id: prediction_root/f'{hashlib.sha256(r.frame_id.encode()).hexdigest()[:24]}.json'
             for r in selected}
    errors_path = output/'prediction_errors.json'
    errors = json.loads(errors_path.read_text()) if errors_path.exists() else {}
    remaining = []
    for record in selected:
        path = files[record.frame_id]
        if path.is_file():
            saved = json.loads(path.read_text())
            if (saved.get('frame_id') != record.frame_id or saved.get('binding') != binding
                    or saved.get('checkpoint_sha256') != binding['checkpoint_sha256']):
                raise ValueError(f'prediction receipt mismatch: {record.frame_id}')
            errors.pop(record.frame_id, None)
            continue
        remaining.append(attached[record.frame_id])
    model, config = load_detector_checkpoint(best)
    device_obj = resolve_device(device)
    if device_info['uuid'] != binding['device_uuid']:
        raise ValueError('prediction device changed from its frozen UUID')
    model.eval().to(device_obj)
    state_dict = torch.load(best, map_location='cpu', weights_only=False)
    normalization = NormalizationStats(**state_dict['normalization'])
    dataset = _InferenceDataset(remaining, normalization, config['size'])
    loader = DataLoader(dataset, batch_size=batch_size, shuffle=False, num_workers=0,
                        collate_fn=_collate_inference)
    done = len(selected)-len(remaining)
    cursor = 0
    for images, metas in loader:
        images = images.to(device_obj)
        batch_rows = remaining[cursor:cursor+len(metas)]
        try:
            batch_predictions = predict_batch_boxes(model, images, metas,
                conf=float(threshold['selected_confidence']), size=config['size'])
        except Exception:
            # Retry independently to retain successful frames and record actual failures.
            batch_predictions = None
        for local, (record, meta) in enumerate(zip(batch_rows, metas)):
            try:
                raw = (batch_predictions[local] if batch_predictions is not None else
                    predict_boxes(model, images[local:local+1], meta,
                        conf=float(threshold['selected_confidence']), size=config['size']))
                boxes = []
                for coords, score in raw:
                    x1, y1, x2, y2 = map(float, coords)
                    h, w = meta.original_size
                    x1, x2 = max(0.0, min(w, x1)), max(0.0, min(w, x2))
                    y1, y2 = max(0.0, min(h, y1)), max(0.0, min(h, y2))
                    if x2 <= x1 or y2 <= y1:
                        continue
                    boxes.append({'xyxy': [x1, y1, x2, y2], 'score': float(score)})
                source = frame_index[record.frame_id]
                if (source['source_anchor_hash'] != record.source_sha256
                        or source['split'] != assignments[record.group_id]
                        or tuple(source['size']) != (meta.original_size[1], meta.original_size[0])):
                    raise ValueError('source identity/native-grid mismatch')
                row = {'frame_id': record.frame_id, 'group_id': record.group_id,
                    'split': assignments[record.group_id], 'domain': record.domain,
                    'source_anchor_hash': record.source_sha256,
                    'width': meta.original_size[1], 'height': meta.original_size[0],
                    'status': 'proposal' if boxes else 'zero_detection_unreviewed',
                    'human_reviewed': False, 'proposal_only': True,
                    'boxes_xyxy_score': boxes, 'checkpoint_sha256': binding['checkpoint_sha256'],
                    'threshold_sha256': binding['threshold_sha256'], 'binding': binding}
                target = files[record.frame_id]
                if target.exists():
                    raise ValueError(f'prediction appeared concurrently: {record.frame_id}')
                write_json(target, row)
                errors.pop(record.frame_id, None)
            except Exception as error:
                errors[record.frame_id] = {'frame_id': record.frame_id,
                    'source_anchor_hash': record.source_sha256,
                    'error': str(error), 'state': 'quarantined_read_or_inference_error_not_negative'}
        cursor += len(metas)
        done += len(metas)
        if done % 128 < len(metas) or done == len(selected):
            write_json(errors_path, errors)
            completed = sum(path.is_file() for path in files.values())
            write_json(prediction_manifest_path, {'binding': binding, 'state': 'predicting',
                'expected_frames': len(selected), 'expected_by_split': dict(expected),
                'completed_frames': completed, 'errors': len(errors),
                'updated_at_utc': datetime.now(timezone.utc).isoformat()})
            print(f'predicted {completed}/{len(selected)}; unresolved read/inference errors={len(errors)}', flush=True)
        if len(errors) and len(errors) % 128 == 0:
            write_json(errors_path, errors)
    # Retry failed frames once with the same model and frozen prediction settings.
    for fid in list(errors):
        record = attached[fid]
        try:
            data = load_frame(record)
            image, scale, padding = letterbox_float(apply_normalization(data, normalization), config['size'])
            meta = SampleMeta(fid, data.shape[:2], scale, padding)
            detections = predict_boxes(model, image[None].to(device_obj), meta,
                conf=float(threshold['selected_confidence']), size=config['size'])
            h, w = data.shape[:2]
            boxes = []
            for coords, score in detections:
                x1, y1, x2, y2 = map(float, coords)
                x1, x2 = max(0.0, min(w, x1)), max(0.0, min(w, x2))
                y1, y2 = max(0.0, min(h, y1)), max(0.0, min(h, y2))
                if x2 > x1 and y2 > y1:
                    boxes.append({'xyxy': [x1, y1, x2, y2], 'score': float(score)})
            source = frame_index[fid]
            if (source['source_anchor_hash'] != record.source_sha256
                    or tuple(source['size']) != (w, h)):
                raise ValueError('source identity/native-grid mismatch on retry')
            row = {'frame_id': fid, 'group_id': record.group_id,
                'split': assignments[record.group_id], 'domain': record.domain,
                'source_anchor_hash': record.source_sha256, 'width': w, 'height': h,
                'status': 'proposal' if boxes else 'zero_detection_unreviewed',
                'human_reviewed': False, 'proposal_only': True, 'boxes_xyxy_score': boxes,
                'checkpoint_sha256': binding['checkpoint_sha256'],
                'threshold_sha256': binding['threshold_sha256'], 'binding': binding}
            write_json(files[fid], row)
            del errors[fid]
        except Exception as error:
            errors[fid]['retry_error'] = str(error)
    write_json(errors_path, errors)
    completed = sum(path.is_file() for path in files.values())
    if completed != len(selected) or errors:
        write_json(prediction_manifest_path, {'binding': binding, 'state': 'incomplete_errors',
            'expected_frames': len(selected), 'completed_frames': completed,
            'errors': len(errors), 'residual_error_ids': sorted(errors)})
        raise RuntimeError(f'prediction incomplete: {completed}/{len(selected)}, errors={len(errors)}')
    prediction_rows = []
    for record in selected:
        row = json.loads(files[record.frame_id].read_text())
        prediction_rows.append(row)
    status_counts = Counter((row['split'], row['status']) for row in prediction_rows)
    result = {'binding': binding, 'state': 'complete', 'expected_frames': len(selected),
        'completed_frames': completed, 'errors': 0, 'by_split': dict(Counter(r['split'] for r in prediction_rows)),
        'status_counts': {split: {status: number for (part, status), number in status_counts.items() if part == split}
                          for split in ('train', 'val', 'test')},
        'checkpoint_sha256': binding['checkpoint_sha256'],
        'threshold_sha256': binding['threshold_sha256'],
        'completed_at_utc': datetime.now(timezone.utc).isoformat()}
    write_json(prediction_manifest_path, result)
    return result


def package_candidates(*, output=DEFAULT_OUTPUT, source_export=DEFAULT_SOURCE_EXPORT,
                       protocol='outputs/protocol_v5', include_zip=True):
    output, source_export, protocol = Path(output), Path(source_export), Path(protocol)
    if (output/'superseded.json').is_file() and not (output/'inputs/human_validation_manifest.json').is_file():
        raise ValueError('refusing to package predictions from a superseded model-selection run')
    state_path = output/'prediction_manifest.json'
    state = json.loads(state_path.read_text())
    if (state.get('state') != 'complete' or state.get('completed_frames') != state.get('expected_frames')
            or state.get('errors')):
        raise ValueError('cannot package until every selected prediction succeeds without read/inference errors')
    source_manifest, frame_index, _, source_manifest_sha, index_sha = _load_frame_index(source_export)
    records, assignments, _ = load_protocol(protocol)
    from pallet.data.eligibility import eligible_records
    records = eligible_records(records)
    records_by_id = {record.frame_id: record for record in records}
    output_root = output/'anylabeling'
    images_root = source_export/'images'
    aux_root = source_export/'auxiliary'
    pred_root = output/'predictions'
    rows = []
    binding = state['binding']
    selection = json.loads((output/'inputs/selection.json').read_text())
    manual_partition = {}
    if (output/'inputs/human_validation_manifest.json').is_file():
        _, train_ids, validation_ids, _, manual_partition = _validated_manual_partition(output, protocol)
        excluded_train_ids = set(train_ids) | set(validation_ids)
        package_slug = 'human_correction_remaining_manual_v2'
    else:
        excluded_train_ids = set(selection['train'])
        package_slug = 'human_correction_remaining_v1'
    external_ids, external_sha = _reviewed_external_exclusions(output, protocol)
    excluded_train_ids |= set(external_ids)
    if external_sha and binding.get('reviewed_external_exclusion_sha256') != external_sha:
        raise ValueError('prediction external-review exclusion binding changed')
    expected_ids = {row.frame_id for row in records
                    if row.frame_id in frame_index and row.frame_id not in excluded_train_ids}
    if len(expected_ids) != state.get('expected_frames'):
        raise ValueError('candidate frame selection differs from the completed prediction manifest')
    if (output/'manual_import_manifest.json').is_file():
        package_slug = f'human_correction_remaining_{len(expected_ids)}_v1'
    root_manifest = source_export/('manifest.json' if (source_export/'manifest.json').exists() else 'package_manifest.json')
    root_sha = file_digest(root_manifest)
    if root_sha != source_manifest_sha or file_digest(source_export/'frames.jsonl') != index_sha:
        raise ValueError('source AnyLabeling export changed after import')
    plan_path = output/'package_plan.json'
    package_plan = {'prediction_binding': binding,
        'source_export_manifest_sha256': source_manifest_sha,
        'source_frame_index_sha256': index_sha, 'expected_frames': len(expected_ids)}
    if plan_path.exists():
        if json.loads(plan_path.read_text()) != package_plan:
            raise ValueError('candidate package plan is bound to different inputs')
    elif output_root.exists() and any(output_root.iterdir()):
        raise ValueError('candidate package output is untracked; use a new output version')
    else:
        write_json(plan_path, package_plan)
    if output_root.exists():
        existing_manifest = output_root/'package_manifest.json'
        if existing_manifest.exists() and json.loads(existing_manifest.read_text()).get('prediction_binding') != binding:
            raise ValueError('candidate package is bound to a different model/checkpoint')
    else:
        output_root.mkdir(parents=True, exist_ok=True)
    if (output_root/'package_manifest.json').exists():
        package_manifest = json.loads((output_root/'package_manifest.json').read_text())
        frame_list = output_root/'frames.jsonl'
        if file_digest(frame_list) != package_manifest['frames_index_sha256']:
            raise ValueError('candidate package frame index changed after publication')
        for line in frame_list.read_text().splitlines():
            row = json.loads(line)
            label_path = output_root/row['annotation']
            image_path = output_root/row['image']
            depth_path = output_root/row['depth']
            validity_path = output_root/row['validity']
            if (not label_path.is_file() or file_digest(label_path) != row['baseline_annotation_sha256']
                    or not image_path.is_file() or file_digest(image_path) != row['view_sha256']['image']
                    or not depth_path.is_file() or file_digest(depth_path) != row['view_sha256']['depth']
                    or not validity_path.is_file() or file_digest(validity_path) != row['view_sha256']['validity']):
                raise ValueError(f'preserving changed candidate package file: {row["frame_id"]}')
    else:
        seen_predictions = set()
        for prediction_path in sorted(pred_root.glob('*.json')):
            prediction = json.loads(prediction_path.read_text())
            fid = prediction['frame_id']
            if fid in seen_predictions or fid not in expected_ids:
                raise ValueError(f'duplicate or unselected prediction: {fid}')
            seen_predictions.add(fid)
            original = frame_index.get(fid)
            record = records_by_id.get(fid)
            if (original is None or record is None
                    or prediction.get('binding') != binding
                    or prediction['source_anchor_hash'] != record.source_sha256
                    or prediction['split'] != assignments[record.group_id]
                    or (prediction.get('width'), prediction.get('height')) != tuple(original['size'])):
                raise ValueError(f'candidate source/selection mismatch: {fid}')
            for box in prediction.get('boxes_xyxy_score', []):
                coords = box.get('xyxy', [])
                if (len(coords) != 4 or not np.isfinite(coords).all()
                        or not 0 <= box.get('score', -1) <= 1
                        or not (0 <= coords[0] < coords[2] <= prediction['width'])
                        or not (0 <= coords[1] < coords[3] <= prediction['height'])):
                    raise ValueError(f'prediction box/score is invalid: {fid}')
            key = Path(original['image']).stem
            split = prediction['split']
            image_rel = Path(original['image'])
            aux_depth_rel = Path(original['depth'])
            aux_valid_rel = Path(original['validity'])
            if (image_rel.parts[1] != split or aux_depth_rel.parts[1] != split
                    or aux_valid_rel.parts[1] != split):
                raise ValueError(f'split differs from source image mapping: {fid}')
            image_src = source_export/image_rel
            depth_src = source_export/aux_depth_rel
            valid_src = source_export/aux_valid_rel
            for source in (image_src, depth_src, valid_src):
                if not source.is_file():
                    raise FileNotFoundError(f'native sensor view is missing: {source}')
            split_dir = output_root/'images'/split
            auxiliary_dir = output_root/'auxiliary'/split
            split_dir.mkdir(parents=True, exist_ok=True)
            auxiliary_dir.mkdir(parents=True, exist_ok=True)
            image_target = split_dir/f'{key}.png'
            depth_target = auxiliary_dir/f'{key}.depth.png'
            valid_target = auxiliary_dir/f'{key}.validity.png'
            # Copy the selected views so a GUI edit cannot mutate the source export.
            for source, target in ((image_src, image_target), (depth_src, depth_target),
                                   (valid_src, valid_target)):
                if target.exists():
                    if file_digest(target) != file_digest(source):
                        raise ValueError(f'candidate sensor view was edited or collides: {target}')
                else:
                    if shutil.disk_usage(output).free < 50*2**30:
                        raise RuntimeError('below 50 GiB disk reserve while assembling correction package')
                    shutil.copy2(source, target)
            boxes = prediction['boxes_xyxy_score']
            shapes = [{'label': 'pallet', 'points': [[box['xyxy'][0], box['xyxy'][1]],
                        [box['xyxy'][2], box['xyxy'][3]]], 'group_id': None,
                        'shape_type': 'rectangle', 'text': '', 'flags': {'proposal_only': True}}
                       for box in boxes]
            json_target = split_dir/f'{key}.json'
            document = {'version': '0.4.43', 'flags': {
                'human_reviewed': False, 'confirmed_negative': False, 'ignore': False,
                'unreviewed': True, 'label_conflict': False, 'proposal_only': True,
                'machine_resolved': False}, 'shapes': shapes, 'imagePath': f'{key}.png',
                'imageData': None, 'imageHeight': prediction['height'],
                'imageWidth': prediction['width'], 'text': '',
                'pallet_prediction': {'frame_id': fid, 'group_id': record.group_id,
                    'domain': record.domain, 'source_anchor_hash': record.source_sha256,
                    'status': prediction['status'], 'confidence': [box['score'] for box in boxes],
                    'checkpoint_sha256': binding['checkpoint_sha256'],
                    'threshold_sha256': binding['threshold_sha256'],
                    'threshold': json.loads((output/'confidence_threshold.json').read_text())['selected_confidence'],
                    'prediction_only': True}}
            rotation = record.sensor_config.get('pixel_rotation_degrees', 0)
            if rotation:
                document['pallet_prediction'].update(pixel_rotation_degrees=rotation,
                    coordinate_frame=f'upright_rotated{rotation}')
            if json_target.exists():
                if json.loads(json_target.read_text()) != document:
                    raise ValueError(f'preserving modified human JSON; create a new candidate package version: {json_target}')
            else:
                write_json(json_target, document)
            rows.append({'frame_id': fid, 'group_id': record.group_id, 'split': split,
                'domain': record.domain, 'status': prediction['status'],
                'proposal_count': len(boxes), 'confidences': [box['score'] for box in boxes],
                'image': str(image_rel), 'annotation': str(json_target.relative_to(output_root)),
                'depth': str(depth_target.relative_to(output_root)),
                'validity': str(valid_target.relative_to(output_root)),
                'source_anchor_hash': record.source_sha256,
                'baseline_annotation_sha256': file_digest(json_target),
                'view_sha256': {'image': file_digest(image_target), 'depth': file_digest(depth_target),
                                'validity': file_digest(valid_target)},
                'prediction_sha256': file_digest(prediction_path),
                'checkpoint_sha256': binding['checkpoint_sha256'],
                'independent_reference': False})
        if len(rows) != len(expected_ids) or {row['frame_id'] for row in rows} != expected_ids:
            raise ValueError(f'candidate package coverage is incomplete: {len(rows)}/{len(expected_ids)} frames')
        rows.sort(key=lambda row: (row['split'], row['frame_id']))
        _write_jsonl(output_root/'frames.jsonl', rows)
        split_counts = Counter(row['split'] for row in rows)
        status_counts = Counter((row['split'], row['status']) for row in rows)
        package_manifest = {'created_at_utc': datetime.now(timezone.utc).isoformat(),
            'kind': 'model_assisted_human_correction_working_labels', 'frames': len(rows),
            'split_counts': dict(split_counts), 'status_counts': {
                split: {status: count for (part, status), count in status_counts.items() if part == split}
                for split in ('train', 'val', 'test')},
            'prediction_binding': binding,
            'checkpoint_sha256': binding['checkpoint_sha256'],
            'threshold_sha256': binding['threshold_sha256'],
            'source_export_manifest_sha256': root_sha,
            'human_reviewed': 0, 'zero_detection_is_negative': False,
            'validation_test_outputs_are_independent_references': False,
            'frames_index_sha256': file_digest(output_root/'frames.jsonl')}
        if manual_partition.get('scope') == AUXILIARY_SCOPE:
            package_manifest.update(scope=AUXILIARY_SCOPE, original_splits_preserved=True,
                                    eligible_for_research_evaluation=False)
        if (output/'inputs/human_validation_manifest.json').is_file():
            quality = json.loads((output/'confidence_threshold.json').read_text())
            manual_partition = json.loads((output/'manual_partition.json').read_text())
            training_metrics = [json.loads(line) for line in
                (output/'training/metrics.jsonl').read_text().splitlines() if line]
            best_epoch = max(training_metrics,
                key=lambda item: item['validation']['AP50_95'])['epoch']
            package_manifest['manual_validation'] = {
                'reference': 'user-confirmed held-out correction-archive annotations',
                'training_frames': len(manual_partition['train_frame_ids']),
                'validation_frames': quality['scored_validation_frames'],
                'validation_boxes': quality['scored_ground_truth_boxes'],
                'validation_status_counts': manual_partition['status_counts']['val'],
                'best_epoch': best_epoch,
                'selected_confidence': quality['selected_confidence'],
                'calibration_recall': quality['selected_validation_metrics']['recall'],
                'calibration_precision': quality['selected_validation_metrics']['precision'],
                'calibration_contains_negative_frames':
                    manual_partition['status_counts']['val'].get('negative', 0) > 0,
                'not_an_independent_generalization_estimate': True}
        write_json(output_root/'package_manifest.json', package_manifest)
        (output_root/'labels.txt').write_text('pallet\n')
        shutil.copy2(source_export/'anylabeling_config.yaml', output_root/'anylabeling_config.yaml')
        val_frames = len(manual_partition['validation_frame_ids']) if (
            output/'manual_partition.json').is_file() else 0
        val_status = (manual_partition['status_counts']['val'] if val_frames else {})
        val_negatives = val_status.get('negative', 0)
        val_boxes = manual_partition['positive_boxes']['val'] if val_frames else 0
        val_train_frames = len(manual_partition['train_frame_ids']) if val_frames else 0
        (output_root/'README_人工修正.md').write_text(
            '这是 YOLO26s 对冻结划分剩余帧生成的人工修正候选包。所有框均为建议，'
            '请逐帧确认托盘实例并勾选 human_reviewed。空框/零检测不代表负例；'
            '确认没有托盘时须勾选 confirmed_negative，不可辨识时勾选 ignore。\n'
            f'val/test中的模型辅助建议不能作为独立盲审参考。本模型使用{val_train_frames}张人工修正帧训练，'
            f'按采集组留出{val_frames}张人工验证帧用于选轮；该验证集不是正式独立测试参考。\n'
            f'人工验证参考含{val_status.get("pos", 0)}张正例、{val_negatives}张确认负例、'
            f'{val_boxes}个托盘框；阈值指标只适用于该验证集。\n'
            '每帧模型、阈值、源帧和图像对应关系见同名 JSON 与 frames.jsonl。\n')
    if not include_zip:
        return package_manifest
    archive = output/f'{package_slug}.zip'
    archive_binding = {'prediction_binding': binding,
        'package_manifest_sha256': file_digest(output_root/'package_manifest.json')}
    zip_state = output/'package_archive_state.json'
    if archive.exists():
        if not zip_state.exists() or json.loads(zip_state.read_text()).get('binding') != archive_binding:
            raise ValueError('archive exists with different/unbound contents; create a new version')
        result = {**package_manifest, 'archive': str(archive), 'archive_sha256': file_digest(archive)}
        if (output/'manual_import_manifest.json').is_file():
            result['audit'] = audit_candidate_package(output=output, source_export=source_export,
                                                       protocol=protocol, archive=archive)
        return result
    if shutil.disk_usage(output).free < 50*2**30:
        raise RuntimeError('below 50 GiB disk reserve')
    temporary = archive.with_suffix('.zip.tmp')
    with zipfile.ZipFile(temporary, 'w', zipfile.ZIP_DEFLATED, compresslevel=1) as bundle:
        for path in sorted(output_root.rglob('*')):
            if path.is_file():
                bundle.write(path, str(Path(package_slug)/path.relative_to(output_root)))
    os.replace(temporary, archive)
    write_json(zip_state, {'binding': archive_binding, 'archive_sha256': file_digest(archive),
                           'bytes': archive.stat().st_size})
    result = {**package_manifest, 'archive': str(archive), 'archive_sha256': file_digest(archive),
              'archive_bytes': archive.stat().st_size}
    if (output/'manual_import_manifest.json').is_file():
        result['audit'] = audit_candidate_package(output=output, source_export=source_export,
                                                   protocol=protocol, archive=archive)
    return result


def audit_candidate_package(*, output, source_export, protocol, archive=None):
    """Verify every proposal sidecar, coordinate, status and ZIP member before delivery."""
    output, source_export, protocol = map(Path, (output, source_export, protocol))
    output_root = output/'anylabeling'
    package_manifest = json.loads((output_root/'package_manifest.json').read_text())
    frame_list = output_root/'frames.jsonl'
    rows = [json.loads(line) for line in frame_list.read_text().splitlines() if line]
    source_manifest, frame_index, _, source_manifest_sha, index_sha = _load_frame_index(source_export)
    records, assignments, _ = load_protocol(protocol)
    records_by_id = {row.frame_id: row for row in records}
    _, train_ids, val_ids, _, partition = _validated_manual_partition(output, protocol)
    excluded_ids = set(train_ids) | set(val_ids)
    external_ids, external_sha = _reviewed_external_exclusions(output, protocol)
    excluded_ids |= set(external_ids)
    expected_ids = {row.frame_id for row in records
                    if row.frame_id in frame_index and row.frame_id not in excluded_ids}
    if len(rows) != len(expected_ids) or {row['frame_id'] for row in rows} != expected_ids:
        raise ValueError(f'candidate package coverage mismatch: {len(rows)}/{len(expected_ids)}')
    split_counts = Counter(row['split'] for row in rows)
    status_counts = Counter((row['split'], row['status']) for row in rows)
    box_count = 0
    for row in rows:
        fid = row['frame_id']
        record = records_by_id.get(fid)
        source_row = frame_index.get(fid)
        if (fid in excluded_ids or record is None or source_row is None
                or record.group_id != row['group_id'] or record.source_sha256 != row['source_anchor_hash']
                or assignments.get(record.group_id) != row['split']
                or row['independent_reference'] is not False):
            raise ValueError(f'candidate source/split/manual-exclusion error: {fid}')
        label_path, image_path = output_root/row['annotation'], output_root/row['image']
        depth_path, valid_path = output_root/row['depth'], output_root/row['validity']
        expected_hashes = row['view_sha256']
        for path, key in ((label_path, 'baseline_annotation_sha256'),
                          (image_path, None), (depth_path, 'depth'), (valid_path, 'validity')):
            if not path.is_file():
                raise FileNotFoundError(path)
        document = json.loads(label_path.read_text())
        metadata = document.get('pallet_prediction') or {}
        w, h = source_row['size']
        if ((document.get('imageWidth'), document.get('imageHeight')) != (w, h)
                or (metadata.get('frame_id'), metadata.get('group_id'),
                    metadata.get('source_anchor_hash')) != (fid, record.group_id, record.source_sha256)
                or document.get('imagePath') != image_path.name
                or label_path.stem != image_path.stem
                or metadata.get('prediction_only') is not True):
            raise ValueError(f'candidate JSON source/coordinate frame mismatch: {fid}')
        flags = document.get('flags', {})
        if not (flags.get('human_reviewed') is False and flags.get('unreviewed') is True
                and flags.get('proposal_only') is True and flags.get('confirmed_negative') is False
                and flags.get('ignore') is False and flags.get('machine_resolved') is False):
            raise ValueError(f'candidate is not marked for human review: {fid}')
        if (file_digest(label_path) != row['baseline_annotation_sha256']
                or file_digest(image_path) != expected_hashes['image']
                or file_digest(depth_path) != expected_hashes['depth']
                or file_digest(valid_path) != expected_hashes['validity']):
            raise ValueError(f'candidate paired-file hash changed: {fid}')
        dimensions = []
        for path in (image_path, depth_path, valid_path):
            with Image.open(path) as image:
                dimensions.append(image.size)
                image.verify()
        if any(size != (w, h) for size in dimensions):
            raise ValueError(f'image/depth/validity native dimensions differ: {fid}')
        boxes = _decode_rectangles(document, w, h)
        if (len(boxes) != row['proposal_count']
                or metadata.get('confidence', []) != row['confidences']):
            raise ValueError(f'candidate box/confidence count mismatch: {fid}')
        confidence = metadata.get('confidence', [])
        if (len(confidence) != len(boxes)
                or any(not np.isfinite(score) or not 0 <= score <= 1 for score in confidence)):
            raise ValueError(f'candidate confidence values are invalid: {fid}')
        if (not boxes and (row['status'] != 'zero_detection_unreviewed'
                           or metadata.get('status') != 'zero_detection_unreviewed')
                or boxes and (row['status'] != 'proposal' or metadata.get('status') != 'proposal')):
            raise ValueError(f'zero-detection/manual status mismatch: {fid}')
        box_count += len(boxes)
    expected_by_split = Counter(assignments[row.group_id] for row in records
                                if row.frame_id in frame_index and row.frame_id not in excluded_ids)
    if split_counts != expected_by_split or dict(split_counts) != package_manifest['split_counts']:
        raise ValueError('candidate package split coverage differs from frozen protocol')
    normalized_status = {split: {status: number for (part, status), number in status_counts.items()
                                 if part == split} for split in ('train', 'val', 'test')}
    if normalized_status != package_manifest['status_counts']:
        raise ValueError('candidate package status totals disagree with its manifest')
    if package_manifest.get('validation_test_outputs_are_independent_references') is not False:
        raise ValueError('candidate validation/test labels cannot claim independent-reference status')

    if archive is None:
        archive = output/f'human_correction_remaining_{len(rows)}_v1.zip'
    archive = Path(archive)
    bad_member = None
    zip_members = 0
    if archive.is_file():
        with zipfile.ZipFile(archive) as bundle:
            bad_member = bundle.testzip()
            zip_members = sum(not item.is_dir() for item in bundle.infolist())
        if bad_member is not None:
            raise ValueError(f'candidate ZIP CRC failed at {bad_member}')
        if zip_members != 4*len(rows)+5:
            raise ValueError(f'candidate ZIP member count mismatch: {zip_members}')
        archive_sha = file_digest(archive)
        zip_crc = 'passed'
    else:
        archive_sha = None
        zip_crc = 'not_requested'
    audit = {'state': 'passed', 'frames': len(rows),
        'split_counts': dict(split_counts),
        'manual_overlap': len({row['frame_id'] for row in rows} & excluded_ids),
        'proposal_frames': status_counts.total() - status_counts.get(('train', 'zero_detection_unreviewed'), 0)
            - status_counts.get(('val', 'zero_detection_unreviewed'), 0)
            - status_counts.get(('test', 'zero_detection_unreviewed'), 0),
        'zero_detection_unreviewed_frames': sum(status_counts.get((split, 'zero_detection_unreviewed'), 0)
                                                 for split in ('train', 'val', 'test')),
        'proposal_boxes': box_count, 'image_json_pairs': len(rows),
        'aligned_depth_validity_pairs': len(rows),
        'all_native_dimensions': 'passed', 'all_xyxy_bounds': 'passed',
        'all_proposals_unreviewed': 'passed', 'zip_members': zip_members,
        'zip_crc': zip_crc, 'zip_sha256': archive_sha,
        'source_export_manifest_sha256': source_manifest_sha,
        'source_frame_index_sha256': index_sha,
        'manual_snapshot_sha256': file_digest(output/'inputs/annotations.jsonl'),
        'training_frames': len(train_ids), 'validation_frames': len(val_ids),
        'validation_test_labels_scored': False,
        'source_archive_set_sha256': partition['source_archive_sha256']}
    if partition.get('scope') == AUXILIARY_SCOPE:
        audit.update(scope=AUXILIARY_SCOPE, eligible_for_research_evaluation=False,
            original_test_labels_used_for_auxiliary_validation=any(
                assignments[records_by_id[fid].group_id] == 'test' for fid in val_ids),
            final_research_test_scored=False)
    write_json(output/'package_audit.json', audit)
    return audit


def main(argv=None):
    from pallet.data.eligibility import active_protocol, active_policy
    control, _ = active_policy()
    source_default = control.get('source_export', str(DEFAULT_SOURCE_EXPORT))
    parser = argparse.ArgumentParser(description=__doc__)
    commands = parser.add_subparsers(dest='stage', required=True)
    imp = commands.add_parser('import')
    imp.add_argument('--archive', default='train.zip')
    imp.add_argument('--source-export', default=source_default)
    imp.add_argument('--protocol', default=active_protocol())
    imp.add_argument('--parent-labels', default=str(DEFAULT_PARENT))
    imp.add_argument('--root', default=str(DEFAULT_ROOT))
    imp.add_argument('--output', default=str(DEFAULT_OUTPUT))
    multi_imp = commands.add_parser('import-manual')
    multi_imp.add_argument('--corrections-config', required=True)
    multi_imp.add_argument('--protocol', default=active_protocol())
    multi_imp.add_argument('--output', default=str(DEFAULT_MANUAL_1330_OUTPUT))
    partition = commands.add_parser('partition')
    partition.add_argument('--source-output', default=str(DEFAULT_OUTPUT))
    partition.add_argument('--output', default=str(DEFAULT_MANUAL_OUTPUT))
    partition.add_argument('--protocol', default=active_protocol())
    partition.add_argument('--seed', type=int, default=42)
    partition.add_argument('--validation-fraction', type=float, default=0.15)
    train = commands.add_parser('train')
    train.add_argument('--output', default=str(DEFAULT_OUTPUT)); train.add_argument('--protocol', default=active_protocol())
    train.add_argument('--root', default=str(DEFAULT_ROOT)); train.add_argument('--device', default=RTX3090_UUID)
    train.add_argument('--epochs', type=int, default=300)
    manual_train = commands.add_parser('train-manual')
    manual_train.add_argument('--output', default=str(DEFAULT_MANUAL_OUTPUT))
    manual_train.add_argument('--protocol', default=active_protocol())
    manual_train.add_argument('--root', default=str(DEFAULT_ROOT))
    manual_train.add_argument('--device', default=RTX3090_UUID)
    manual_train.add_argument('--epochs', type=int, default=300)
    manual_train.add_argument('--batch-size', type=int, default=4)
    manual_train.add_argument('--workers', type=int, default=0)
    manual_train.add_argument('--validation-batch-size', type=int, default=1)
    calibrate = commands.add_parser('calibrate')
    calibrate.add_argument('--output', default=str(DEFAULT_OUTPUT)); calibrate.add_argument('--protocol', default=active_protocol())
    calibrate.add_argument('--root', default=str(DEFAULT_ROOT)); calibrate.add_argument('--device', default=RTX3090_UUID)
    predict = commands.add_parser('predict')
    predict.add_argument('--output', default=str(DEFAULT_OUTPUT)); predict.add_argument('--protocol', default=active_protocol())
    predict.add_argument('--root', default=str(DEFAULT_ROOT)); predict.add_argument('--source-export', default=source_default)
    predict.add_argument('--device', default=RTX3090_UUID); predict.add_argument('--batch-size', type=int, default=4)
    package = commands.add_parser('package')
    package.add_argument('--output', default=str(DEFAULT_OUTPUT)); package.add_argument('--source-export', default=source_default)
    package.add_argument('--protocol', default=active_protocol()); package.add_argument('--no-zip', action='store_true')
    audit = commands.add_parser('audit-package')
    audit.add_argument('--output', default=str(DEFAULT_MANUAL_1330_OUTPUT))
    audit.add_argument('--source-export', default=source_default)
    audit.add_argument('--protocol', default=active_protocol())
    args = parser.parse_args(argv)
    if args.stage == 'import':
        result = import_corrections(archive=args.archive, source_export=args.source_export,
            protocol=args.protocol, parent_labels=args.parent_labels, root=args.root, output=args.output)
    elif args.stage == 'import-manual':
        result = import_manual_correction_archives(corrections_config=args.corrections_config,
            protocol=args.protocol, output=args.output)
    elif args.stage == 'partition':
        result = create_manual_validation_partition(source_output=args.source_output,
            output=args.output, protocol=args.protocol, seed=args.seed,
            validation_fraction=args.validation_fraction)
        source_output = Path(args.source_output)
        if (source_output.resolve() != Path(args.output).resolve()
                and (source_output/'import_manifest.json').is_file()
                and not (source_output/'manual_import_manifest.json').is_file()):
            write_json(source_output/'superseded.json', {'state': 'superseded_for_selection_and_prediction',
                'reason': 'user restricted this legacy auxiliary run to its supplied manual labels',
                'fitted_manual_labels_sha256': result['manual_annotations_sha256'],
                'replacement_partition': str(Path(args.output).resolve()/'manual_partition.json'),
                'replacement_partition_sha256': file_digest(Path(args.output)/'manual_partition.json'),
                'training_frame_count': len(result['train_frame_ids']),
                'old_best_checkpoint_allowed_for_prediction': False,
                'old_confidence_threshold_allowed_for_prediction': False})
    elif args.stage == 'train':
        result = train_assistant(output=args.output, protocol=args.protocol, root=args.root,
                                 device=args.device, epochs=args.epochs)
    elif args.stage == 'train-manual':
        result = train_manual_validation_assistant(output=args.output, protocol=args.protocol,
            root=args.root, device=args.device, epochs=args.epochs,
            batch_size=args.batch_size, workers=args.workers,
            validation_batch_size=args.validation_batch_size)
    elif args.stage == 'calibrate':
        result = calibrate_threshold(output=args.output, protocol=args.protocol,
                                     root=args.root, device=args.device)
    elif args.stage == 'predict':
        result = predict_remaining(output=args.output, protocol=args.protocol, root=args.root,
            source_export=args.source_export, device=args.device, batch_size=args.batch_size)
    elif args.stage == 'package':
        result = package_candidates(output=args.output, source_export=args.source_export,
            protocol=args.protocol, include_zip=not args.no_zip)
    else:
        result = audit_candidate_package(output=args.output, source_export=args.source_export,
                                         protocol=args.protocol)
    print(json.dumps(result, ensure_ascii=False, indent=2))


if __name__ == '__main__':
    main()
