truf-server/app/docker_depth_experiment.py

import copy
from datetime import datetime, timezone
import hashlib
import inspect
import io
import json
import math
import os
import re
import textwrap
import tokenize
from dataclasses import dataclass
from typing import Optional

from target_identity import (
    DOCKER_DIGEST_RE,
    DOCKER_IMAGE_RE,
    DOCKER_REVISION_RE,
    DOCKER_TAG_TARGET_SCHEMA,
    normalize_docker_digest,
    parse_docker_target,
    serialize_docker_tag_target,
    validate_docker_image_reference,
)


DOCKER_DEPTH_SELECTOR_VERSION = 'docker-layer-graph-v2'
DOCKER_RANK1_BREADTH_SELECTOR_VERSION = 'docker-rank1-breadth-v1'
DOCKER_DEPTH_QUERY_COUNT = 61
DOCKER_DEPTH_ORDINARY_IMAGES_PER_REPOSITORY = 3
DOCKER_DEPTH_REPOSITORIES_PER_QUERY = 10
DOCKER_DEPTH_SHALLOW_IMAGES_PER_REPOSITORY = 1
DOCKER_DEPTH_DEEP_REPOSITORIES_PER_QUERY = 1
DOCKER_DEPTH_DEEP_IMAGES_PER_REPOSITORY = 10
DOCKER_DEPTH_MAX_UNIQUE_TARGETS = 1200
DOCKER_RANK1_BREADTH_REPOSITORIES_PER_QUERY = 39
DOCKER_RANK1_BREADTH_MAX_UNIQUE_TARGETS = 2000
DOCKERHUB_DISCOVERY_MAX_PAGES = 30
DOCKERHUB_DISCOVERY_MAX_PER_PAGE = 100
DOCKERHUB_DISCOVERY_ALGORITHM_VERSION = 1
DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS = 250000
DOCKER_DEPTH_RESOLVER_MAX_ATTEMPTS = 3
DOCKER_DEPTH_RESOLVER_RETRY_SECONDS = 300
DOCKER_DEPTH_RESOLVER_RETRY_MAX_SECONDS = 3600
DOCKER_DEPTH_COLLECTION_GENERATION = 'docker-depth-provenance-v1'
DOCKER_DEPTH_COHORT_PLAN_TYPE = 'truf-docker-depth-cohort-plan-v2'
DOCKER_DEPTH_COHORT_MANIFEST_TYPE = 'truf-docker-depth-cohort-review-v2'
DOCKER_DEPTH_HOLD_MANIFEST_TYPE = 'truf-docker-depth-hold-review-v1'
DOCKER_DEPTH_REACTIVATION_MANIFEST_TYPE = 'truf-docker-depth-reactivation-review-v1'
DOCKER_DEPTH_RESOLVER_REFUND_MANIFEST_TYPE = (
    'truf-docker-depth-resolver-attempt-refund-v1'
)
DOCKER_DEPTH_RESOLVER_REFUND_KIND = 'zero_graph_limit_v1'
DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS = 2
DOCKER_DEPTH_RESOLVER_REFUND_LOG_MAX_BYTES = 64 * 1024 * 1024
DOCKER_DEPTH_RESOLVER_REFUND_OLD_ERROR = (
    'Docker replacement candidate pool must contain 1 through 100 graphs'
)
DOCKER_DEPTH_HOLD_REASON = 'docker_depth_experiment_hold'
DOCKER_DEPTH_DYNAMIC_HOLD_REASON = 'docker_depth_experiment_dynamic_hold'
DOCKER_DEPTH_RELEASE_REASON = 'docker_depth_experiment_reviewed_release'
DOCKER_DEPTH_REPOSITORY_SKIP_REASON = 'no_eligible_physical_target'
DOCKER_DEPTH_REMOTE_UNAVAILABLE_SKIP_REASON = 'remote_unavailable_after_attempt_limit'
DOCKER_DEPTH_RESOLVER_DISPOSITION_MANIFEST_TYPE = (
    'truf-docker-depth-resolver-disposition-v1'
)
DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND = (
    'resolver_attempt_limit_replace_or_skip_v1'
)
DOCKER_DEPTH_HOLD_ACTIVE_STATES = frozenset({
    'holding', 'resolving', 'active', 'draining', 'completed', 'held',
})

_DOCKER_EXPERIMENT_PROFILES = {
    DOCKER_DEPTH_SELECTOR_VERSION: {
        'query_count': DOCKER_DEPTH_QUERY_COUNT,
        'repositories_per_query': DOCKER_DEPTH_REPOSITORIES_PER_QUERY,
        'shallow_images_per_repository': DOCKER_DEPTH_SHALLOW_IMAGES_PER_REPOSITORY,
        'deep_repositories_per_query': DOCKER_DEPTH_DEEP_REPOSITORIES_PER_QUERY,
        'images_per_repository': DOCKER_DEPTH_DEEP_IMAGES_PER_REPOSITORY,
        'target_limit': DOCKER_DEPTH_MAX_UNIQUE_TARGETS,
        'theoretical_max_targets': DOCKER_DEPTH_QUERY_COUNT * (
            DOCKER_DEPTH_REPOSITORIES_PER_QUERY
            + DOCKER_DEPTH_DEEP_IMAGES_PER_REPOSITORY - 1
        ),
    },
    DOCKER_RANK1_BREADTH_SELECTOR_VERSION: {
        'query_count': DOCKER_DEPTH_QUERY_COUNT,
        'repositories_per_query': DOCKER_RANK1_BREADTH_REPOSITORIES_PER_QUERY,
        'shallow_images_per_repository': 1,
        'deep_repositories_per_query': 1,
        'images_per_repository': 1,
        'target_limit': DOCKER_RANK1_BREADTH_MAX_UNIQUE_TARGETS,
        'theoretical_max_targets': DOCKER_RANK1_BREADTH_MAX_UNIQUE_TARGETS,
    },
}


def reviewed_docker_experiment_profile(selector_version):
    try:
        return dict(_DOCKER_EXPERIMENT_PROFILES[selector_version])
    except KeyError:
        raise ValueError('Docker experiment selector_version is not reviewed') from None

DOCKER_DEPTH_EXPERIMENT_KEYS = frozenset({
    'experiment_key',
    'enabled',
    'queries',
    'repositories_per_query',
    'shallow_images_per_repository',
    'deep_repositories_per_query',
    'deep_images_per_repository',
    'target_limit',
    'selector_version',
})

_IDENTIFIER_RE = re.compile(r'^[a-z0-9](?:[a-z0-9._-]{0,126}[a-z0-9])?$')
_PLATFORM_COMPONENT_RE = re.compile(r'^[a-z0-9][a-z0-9._-]{0,63}$')
_POSTGRES_URL_RE = re.compile(r'^postgres(?:ql)?://', re.IGNORECASE)
_SELECTOR_DISTINCT_GRAPH = 'ordered-layer-digests'
_SELECTOR_FIRST_THREE_STEPS = (
    'newest_distinct_graph',
    'maximum_marginal_layer_novelty',
    'oldest_distinct_graph',
)
_SELECTOR_LATER_SCORE = 'maximum_marginal_layer_novelty'
_SELECTOR_LATER_TIE_BREAKS = (
    'maximum_minimum_temporal_distance',
    'newest_update',
    'normalized_target',
    'ordered_graph_sha256',
)


@dataclass(frozen=True)
class DockerDepthExperimentConfig:
    experiment_key: str
    enabled: bool
    collection_generation: str
    queries: tuple
    repositories_per_query: int
    shallow_images_per_repository: int
    deep_repositories_per_query: int
    deep_images_per_repository: int
    target_limit: int
    selector_version: str
    theoretical_max_targets: int
    ordered_query_hash: str
    config_hash: str
    selector_hash: str

    @property
    def ordered_query_sha256(self):
        return self.ordered_query_hash

    @property
    def ordered_queries_sha256(self):
        return self.ordered_query_hash

    @property
    def config_sha256(self):
        return self.config_hash

    @property
    def selector_sha256(self):
        return self.selector_hash


@dataclass(frozen=True)
class ValidatedDockerDepthConfig:
    normalized_config: dict
    docker_images_per_repository: int
    experiment: Optional[DockerDepthExperimentConfig] = None
    ordered_query_hash: str = ''
    config_hash: str = ''
    selector_hash: str = ''

    @property
    def config(self):
        return copy.deepcopy(self.normalized_config)

    @property
    def ordered_query_sha256(self):
        return self.ordered_query_hash

    @property
    def ordered_queries_sha256(self):
        return self.ordered_query_hash

    @property
    def config_sha256(self):
        return self.config_hash

    @property
    def selector_sha256(self):
        return self.selector_hash


def _canonical_sha256(value):
    payload = json.dumps(
        value,
        ensure_ascii=True,
        allow_nan=False,
        sort_keys=True,
        separators=(',', ':'),
    ).encode('utf-8')
    return hashlib.sha256(payload).hexdigest()


def canonical_ordered_query_hash(queries):
    return _canonical_sha256(list(queries))


def canonical_dockerhub_discovery_policy(pages, per_page, sort_by, sort_order):
    if isinstance(pages, bool) or not isinstance(pages, int) or not 1 <= pages <= DOCKERHUB_DISCOVERY_MAX_PAGES:
        raise ValueError(
            f'DockerHub discovery pages must be an integer from 1 through {DOCKERHUB_DISCOVERY_MAX_PAGES}'
        )
    if (
        isinstance(per_page, bool)
        or not isinstance(per_page, int)
        or not 1 <= per_page <= DOCKERHUB_DISCOVERY_MAX_PER_PAGE
    ):
        raise ValueError(
            'DockerHub discovery per_page must be an integer from 1 through '
            f'{DOCKERHUB_DISCOVERY_MAX_PER_PAGE}'
        )
    if not isinstance(sort_by, str) or not sort_by or sort_by != sort_by.strip():
        raise ValueError('DockerHub discovery sort_by must be a non-empty canonical string')
    if sort_order not in ('asc', 'desc'):
        raise ValueError("DockerHub discovery sort_order must be 'asc' or 'desc'")
    payload = {
        'algorithm_version': DOCKERHUB_DISCOVERY_ALGORITHM_VERSION,
        'page_hard_cap': DOCKERHUB_DISCOVERY_MAX_PAGES,
        'pages': pages,
        'per_page': per_page,
        'per_page_hard_cap': DOCKERHUB_DISCOVERY_MAX_PER_PAGE,
        'sort_by': sort_by,
        'sort_order': sort_order,
    }
    return {**payload, 'policy_sha256': _canonical_sha256(payload)}


def canonical_selector_hash(selector_version):
    return _canonical_sha256({
        'identity': {
            'dependencies': {
                'docker_digest_pattern': DOCKER_DIGEST_RE.pattern,
                'docker_image_pattern': DOCKER_IMAGE_RE.pattern,
                'docker_revision_pattern': DOCKER_REVISION_RE.pattern,
                'docker_target_schema': DOCKER_TAG_TARGET_SCHEMA,
            },
            'distinct_graph': _SELECTOR_DISTINCT_GRAPH,
            'first_three': _SELECTOR_FIRST_THREE_STEPS,
            'implementation_sha256': _selector_implementation_sha256(),
            'later_score': _SELECTOR_LATER_SCORE,
            'later_tie_breaks': _SELECTOR_LATER_TIE_BREAKS,
        },
        'version': selector_version,
    })


def canonical_docker_layer_graph_hash(layers):
    return _canonical_sha256(list(layers))


def canonical_docker_descriptor_hash(digest, media_type, size_bytes):
    return _canonical_sha256({
        'digest': str(digest),
        'media_type': str(media_type),
        'size_bytes': int(size_bytes),
    })


def canonical_docker_depth_selection_evidence_hash(evidence):
    normalized = dict(evidence)
    # Repository tag churn may change this audit metric after rank-one selection.
    normalized.pop('candidate_distinct_graph_count', None)
    return _canonical_sha256(normalized)


def validate_docker_images_per_repository(value):
    if isinstance(value, bool) or not isinstance(value, int):
        raise ValueError('docker_images_per_repository must be an integer from 1 through 10')
    if value < 1 or value > 10:
        raise ValueError('docker_images_per_repository must be an integer from 1 through 10')
    return value


def _selector_graph_layers(candidate):
    layers = candidate.get('layers')
    if not isinstance(layers, (list, tuple)) or not layers:
        return None
    graph = []
    for layer in layers:
        digest = normalize_docker_digest(
            layer.get('digest') if isinstance(layer, dict) else layer
        )
        if not digest:
            return None
        graph.append(digest)
    return tuple(graph)


def _selector_graph_timestamp(value):
    if isinstance(value, bool):
        return float('-inf')
    try:
        timestamp = float(value)
        return timestamp if math.isfinite(timestamp) else float('-inf')
    except (TypeError, ValueError, OverflowError):
        pass
    if isinstance(value, str):
        try:
            parsed = datetime.fromisoformat(value.strip().replace('Z', '+00:00'))
            if parsed.tzinfo is None:
                parsed = parsed.replace(tzinfo=timezone.utc)
            return parsed.timestamp()
        except (ValueError, OverflowError, OSError):
            pass
    return float('-inf')


def _selector_graph_target(candidate):
    target = str(candidate.get('target') or '').strip()
    try:
        return parse_docker_target(target)['target'].lower()
    except (TypeError, ValueError):
        return target.lower()


def _selector_graph_selection_record(candidate, rank, reason, marginal_layers):
    record = {
        key: value for key, value in candidate.items()
        if not key.startswith('_selector_') and key != 'layer_descriptors'
    }
    graph = candidate['_selector_graph']
    layer_count = len(graph)
    descriptors = candidate.get('layer_descriptors')
    if isinstance(descriptors, (tuple, list)) and len(descriptors) == layer_count:
        layer_metadata = tuple({
            'digest': descriptor['digest'],
            'media_type': descriptor['media_type'],
            'size_bytes': descriptor['size'],
            'descriptor_sha256': canonical_docker_descriptor_hash(
                descriptor['digest'], descriptor['media_type'], descriptor['size'],
            ),
            'position_from_base': position,
            'position_from_top': layer_count - position + 1,
        } for position, descriptor in enumerate(descriptors, 1))
    else:
        layer_metadata = tuple({
            'digest': digest,
            'position_from_base': position,
            'position_from_top': layer_count - position + 1,
        } for position, digest in enumerate(graph, 1))
    record.update({
        'rank': rank,
        'image_rank': rank,
        'reason': reason,
        'selection_reason': reason,
        'graph': graph,
        'graph_hash': candidate['_selector_graph_hash'],
        'graph_sha256': candidate['_selector_graph_hash'],
        'layers': graph,
        'layer_count': layer_count,
        'marginal_layer_count': marginal_layers,
        'layer_metadata': layer_metadata,
    })
    return record


def select_docker_layer_graphs(candidates, limit=1, *, replacement_pool=False):
    if replacement_pool:
        if isinstance(limit, bool) or not isinstance(limit, int) or not 1 <= limit <= 100:
            raise ValueError('Docker replacement candidate pool must contain 1 through 100 graphs')
    else:
        limit = validate_docker_images_per_repository(limit)

    def source_index(candidate):
        value = candidate.get('source_index', 0)
        if isinstance(value, bool):
            return 0
        try:
            return int(value)
        except (TypeError, ValueError, OverflowError):
            return 0

    def order_key(candidate):
        return (
            -candidate['_selector_updated_at'],
            source_index(candidate),
            _selector_graph_target(candidate),
        )

    valid = []
    for item in candidates or ():
        if not isinstance(item, dict):
            continue
        candidate = dict(item)
        graph = _selector_graph_layers(candidate)
        if graph is None:
            continue
        candidate['_selector_graph'] = graph
        candidate['_selector_graph_hash'] = canonical_docker_layer_graph_hash(graph)
        candidate['_selector_updated_at'] = _selector_graph_timestamp(candidate.get('updated_at'))
        valid.append(candidate)

    distinct = []
    seen_graphs = set()
    for candidate in sorted(valid, key=order_key):
        graph = candidate['_selector_graph']
        if graph in seen_graphs:
            continue
        seen_graphs.add(graph)
        distinct.append(candidate)
    if not distinct:
        return []

    selected = []
    first = distinct.pop(0)
    covered_layers = set(first['_selector_graph'])
    selected.append((first, _SELECTOR_FIRST_THREE_STEPS[0], len(covered_layers)))

    if limit >= 2 and distinct:
        index = max(
            range(len(distinct)),
            key=lambda position: (
                len(set(distinct[position]['_selector_graph']) - covered_layers),
                -position,
            ),
        )
        candidate = distinct.pop(index)
        marginal = len(set(candidate['_selector_graph']) - covered_layers)
        selected.append((candidate, _SELECTOR_FIRST_THREE_STEPS[1], marginal))
        covered_layers.update(candidate['_selector_graph'])

    if limit >= 3 and distinct:
        candidate = distinct.pop()
        marginal = len(set(candidate['_selector_graph']) - covered_layers)
        selected.append((candidate, _SELECTOR_FIRST_THREE_STEPS[2], marginal))
        covered_layers.update(candidate['_selector_graph'])

    while len(selected) < limit and distinct:
        selected_times = [
            candidate['_selector_updated_at'] for candidate, _reason, _marginal in selected
            if math.isfinite(candidate['_selector_updated_at'])
        ]

        def later_key(candidate):
            updated_at = candidate['_selector_updated_at']
            temporal_distance = (
                min(abs(updated_at - selected_at) for selected_at in selected_times)
                if math.isfinite(updated_at) and selected_times
                else float('-inf')
            )
            return (
                -len(set(candidate['_selector_graph']) - covered_layers),
                -temporal_distance,
                -updated_at,
                _selector_graph_target(candidate),
                candidate['_selector_graph_hash'],
            )

        candidate = min(distinct, key=later_key)
        distinct.remove(candidate)
        marginal = len(set(candidate['_selector_graph']) - covered_layers)
        selected.append((candidate, _SELECTOR_LATER_SCORE, marginal))
        covered_layers.update(candidate['_selector_graph'])

    return [
        _selector_graph_selection_record(candidate, rank, reason, marginal)
        for rank, (candidate, reason, marginal) in enumerate(selected, 1)
    ]


def _canonical_selector_source(function):
    try:
        source = textwrap.dedent(inspect.getsource(function))
    except (OSError, TypeError) as exc:
        raise RuntimeError('Docker depth selector source authority is unavailable') from exc
    canonical = []
    ignored = {
        tokenize.COMMENT, tokenize.ENCODING, tokenize.ENDMARKER, tokenize.NL,
    }
    structural = {tokenize.INDENT, tokenize.DEDENT, tokenize.NEWLINE}
    for token in tokenize.generate_tokens(io.StringIO(source).readline):
        if token.type in ignored:
            continue
        if token.type in structural:
            canonical.append(tokenize.tok_name[token.type])
        else:
            canonical.append(f'{tokenize.tok_name[token.type]}:{token.string}')
    return '\n'.join(canonical)


def _selector_implementation_sha256(source_functions=None):
    if source_functions is None:
        source_functions = (
            _canonical_sha256,
            canonical_docker_layer_graph_hash,
            canonical_docker_descriptor_hash,
            validate_docker_images_per_repository,
            normalize_docker_digest,
            validate_docker_image_reference,
            serialize_docker_tag_target,
            parse_docker_target,
            _selector_graph_layers,
            _selector_graph_timestamp,
            _selector_graph_target,
            _selector_graph_selection_record,
            select_docker_layer_graphs,
        )
    payload = '\nFUNCTION\n'.join(
        _canonical_selector_source(function) for function in source_functions
    ).encode('utf-8')
    return hashlib.sha256(payload).hexdigest()


def _strict_integer(mapping, key, minimum=1, maximum=None):
    value = mapping.get(key)
    if isinstance(value, bool) or not isinstance(value, int):
        raise ValueError(f'docker_depth_experiment.{key} must be an integer')
    if value < minimum or (maximum is not None and value > maximum):
        upper = f' through {maximum}' if maximum is not None else ''
        raise ValueError(
            f'docker_depth_experiment.{key} must be from {minimum}{upper}'
        )
    return value


def _strict_identifier(value, name):
    if not isinstance(value, str) or not _IDENTIFIER_RE.fullmatch(value):
        raise ValueError(
            f'docker_depth_experiment.{name} must be a lowercase stable identifier'
        )
    return value


def _strict_config_integer(value, name, minimum=0, maximum=None):
    if isinstance(value, bool) or not isinstance(value, int):
        raise ValueError(f'{name} must be an integer')
    if value < minimum or (maximum is not None and value > maximum):
        upper = f' through {maximum}' if maximum is not None else ' or greater'
        raise ValueError(f'{name} must be from {minimum}{upper}')
    return value


def validate_dockerhub_discovery_policies(source, queries=None):
    """Return strict ordered effective query policies without runtime side effects."""
    if not isinstance(source, dict):
        raise ValueError('sources.dockerhub must be a mapping')
    configured_queries = source.get('queries') if queries is None else list(queries)
    if not isinstance(configured_queries, list):
        raise ValueError('sources.dockerhub.queries must be an ordered list')
    configured_queries = tuple(configured_queries)
    if any(
        not isinstance(query, str)
        or not query
        or query != query.strip()
        for query in configured_queries
    ):
        raise ValueError('sources.dockerhub.queries contains a malformed query')
    if len(set(configured_queries)) != len(configured_queries):
        raise ValueError('sources.dockerhub.queries must be unique')

    pages = _strict_config_integer(
        source.get('pages', 1), 'sources.dockerhub.pages', 1,
        DOCKERHUB_DISCOVERY_MAX_PAGES,
    )
    per_page = _strict_config_integer(
        source.get('per_page', 50), 'sources.dockerhub.per_page', 1,
        DOCKERHUB_DISCOVERY_MAX_PER_PAGE,
    )
    max_targets = _strict_config_integer(
        source.get('max_targets', 0), 'sources.dockerhub.max_targets', 0,
    )
    sort_by = source.get('docker_sort_by', source.get('sort_by', 'updated_at'))
    sort_order = source.get('sort_order', 'desc')
    canonical_dockerhub_discovery_policy(pages, per_page, sort_by, sort_order)

    overrides = source.get('query_overrides', {})
    if not isinstance(overrides, dict):
        raise ValueError('sources.dockerhub.query_overrides must be a mapping')
    unknown_queries = [query for query in overrides if query not in configured_queries]
    if unknown_queries:
        names = ', '.join(sorted(repr(query) for query in unknown_queries))
        raise ValueError(
            'sources.dockerhub.query_overrides contains unconfigured queries: ' + names
        )

    effective = []
    for query in configured_queries:
        override = overrides.get(query, {})
        if not isinstance(override, dict):
            raise ValueError(
                f'sources.dockerhub.query override for {query!r} must be a mapping'
            )
        unknown = set(override) - {'pages', 'per_page', 'max_targets'}
        if unknown:
            raise ValueError(
                f'sources.dockerhub query override for {query!r} has unsupported keys: '
                + ', '.join(sorted(repr(key) for key in unknown))
            )
        effective_pages = _strict_config_integer(
            override.get('pages', pages),
            f'sources.dockerhub query override pages for {query!r}', 1,
            DOCKERHUB_DISCOVERY_MAX_PAGES,
        )
        effective_per_page = _strict_config_integer(
            override.get('per_page', per_page),
            f'sources.dockerhub query override per_page for {query!r}', 1,
            DOCKERHUB_DISCOVERY_MAX_PER_PAGE,
        )
        effective_max_targets = _strict_config_integer(
            override.get('max_targets', max_targets),
            f'sources.dockerhub query override max_targets for {query!r}', 0,
        )
        policy = canonical_dockerhub_discovery_policy(
            effective_pages, effective_per_page, sort_by, sort_order,
        )
        effective.append({
            'query': query,
            **policy,
            'max_targets': effective_max_targets,
        })
    return tuple(effective)


def _docker_source(config):
    sources = config.get('sources')
    if sources is None:
        sources = {}
    if not isinstance(sources, dict):
        raise ValueError('sources must be a mapping')
    source = sources.get('dockerhub')
    if source is None:
        source = {}
    if not isinstance(source, dict):
        raise ValueError('sources.dockerhub must be a mapping')
    return source


def validate_docker_depth_config(
    config, *, managed_postgres=None, final_cutover=None,
):
    """Validate and copy Docker depth configuration without runtime side effects."""
    if not isinstance(config, dict):
        raise ValueError('configuration root must be a mapping')
    normalized = copy.deepcopy(config)
    global_config = normalized.get('global')
    if global_config is None:
        global_config = {}
    if not isinstance(global_config, dict):
        raise ValueError('global must be a mapping')
    source = _docker_source(normalized)

    configured_depths = []
    if 'docker_images_per_repository' in global_config:
        configured_depths.append((global_config, 'global'))
    if 'docker_images_per_repository' in source:
        configured_depths.append((source, 'sources.dockerhub'))
    for owner, _name in configured_depths:
        validate_docker_images_per_repository(owner['docker_images_per_repository'])
    image_depth = source.get(
        'docker_images_per_repository',
        global_config.get('docker_images_per_repository', 1),
    )
    image_depth = validate_docker_images_per_repository(image_depth)

    experiment_mapping = source.get('docker_depth_experiment')
    if experiment_mapping is None:
        return ValidatedDockerDepthConfig(normalized, image_depth)
    if not isinstance(experiment_mapping, dict):
        raise ValueError('docker_depth_experiment must be a mapping')

    unknown = sorted(set(experiment_mapping) - DOCKER_DEPTH_EXPERIMENT_KEYS)
    if unknown:
        raise ValueError(
            'docker_depth_experiment has unsupported keys: ' + ', '.join(unknown)
        )
    missing = sorted(DOCKER_DEPTH_EXPERIMENT_KEYS - set(experiment_mapping))
    if missing:
        raise ValueError(
            'docker_depth_experiment is missing required keys: ' + ', '.join(missing)
        )

    experiment_key = _strict_identifier(
        experiment_mapping['experiment_key'], 'experiment_key',
    )
    enabled = experiment_mapping['enabled']
    if not isinstance(enabled, bool):
        raise ValueError('docker_depth_experiment.enabled must be a boolean')
    selector_version = _strict_identifier(
        experiment_mapping['selector_version'], 'selector_version',
    )
    profile = reviewed_docker_experiment_profile(selector_version)

    queries_value = experiment_mapping['queries']
    if not isinstance(queries_value, list):
        raise ValueError('docker_depth_experiment.queries must be an ordered list')
    queries = tuple(queries_value)
    if len(queries) != DOCKER_DEPTH_QUERY_COUNT:
        raise ValueError(
            f'docker_depth_experiment.queries must contain exactly {DOCKER_DEPTH_QUERY_COUNT} queries'
        )
    if any(
        not isinstance(query, str)
        or not query
        or query != query.strip()
        for query in queries
    ):
        raise ValueError('docker_depth_experiment.queries contains a malformed query')
    if len(set(queries)) != len(queries):
        raise ValueError('docker_depth_experiment.queries must be unique')
    source_queries = source.get('queries')
    if not isinstance(source_queries, list) or tuple(source_queries) != queries:
        raise ValueError(
            'docker_depth_experiment.queries must exactly match ordered sources.dockerhub.queries'
        )

    repositories_per_query = _strict_integer(
        experiment_mapping, 'repositories_per_query', maximum=100,
    )
    shallow_images = _strict_integer(
        experiment_mapping, 'shallow_images_per_repository', maximum=10,
    )
    deep_repositories = _strict_integer(
        experiment_mapping, 'deep_repositories_per_query', maximum=100,
    )
    deep_images = _strict_integer(
        experiment_mapping, 'deep_images_per_repository', maximum=10,
    )
    target_limit = _strict_integer(
        experiment_mapping, 'target_limit', maximum=1000000,
    )
    if deep_repositories > repositories_per_query:
        raise ValueError(
            'docker_depth_experiment deep repositories exceed repositories_per_query'
        )
    if shallow_images > deep_images:
        raise ValueError(
            'docker_depth_experiment shallow image depth exceeds deep image depth'
        )
    theoretical_max = len(queries) * (
        repositories_per_query * shallow_images
        + deep_repositories * (deep_images - shallow_images)
    )
    if (
        selector_version == DOCKER_DEPTH_SELECTOR_VERSION
        and theoretical_max > target_limit
    ):
        raise ValueError(
            'docker_depth_experiment theoretical target maximum exceeds target_limit'
        )

    fixed_limits = {
        'repositories_per_query': profile['repositories_per_query'],
        'shallow_images_per_repository': profile['shallow_images_per_repository'],
        'deep_repositories_per_query': profile['deep_repositories_per_query'],
        'deep_images_per_repository': profile['images_per_repository'],
        'target_limit': profile['target_limit'],
    }
    for key, expected in fixed_limits.items():
        if experiment_mapping[key] != expected:
            raise ValueError(
                f'docker_depth_experiment.{key} must equal {expected}'
            )
    theoretical_max = profile['theoretical_max_targets']
    if image_depth != DOCKER_DEPTH_ORDINARY_IMAGES_PER_REPOSITORY:
        raise ValueError(
            'docker_images_per_repository must equal the reviewed ordinary '
            f'resolver depth {DOCKER_DEPTH_ORDINARY_IMAGES_PER_REPOSITORY}'
        )

    effective_policies = validate_dockerhub_discovery_policies(source, queries)
    if len({policy['policy_sha256'] for policy in effective_policies}) != 1:
        raise ValueError(
            'docker_depth_experiment requires one consistent pages/per_page '
            'discovery policy across all queries'
        )

    configured_platform_filters = []
    if 'docker_platform_filter_enabled' in global_config:
        configured_platform_filters.append(global_config['docker_platform_filter_enabled'])
    if 'docker_platform_filter_enabled' in source:
        configured_platform_filters.append(source['docker_platform_filter_enabled'])
    if any(not isinstance(value, bool) for value in configured_platform_filters):
        raise ValueError('docker_platform_filter_enabled must be a boolean')
    platform_filter_enabled = source.get(
        'docker_platform_filter_enabled',
        global_config.get('docker_platform_filter_enabled', True),
    )

    def platform_component(key, default):
        configured = []
        if key in global_config:
            configured.append(global_config[key])
        if key in source:
            configured.append(source[key])
        for value in configured:
            if (
                not isinstance(value, str)
                or not _PLATFORM_COMPONENT_RE.fullmatch(value)
                or value != value.lower()
            ):
                raise ValueError(f'{key} must be a lowercase Docker platform identifier')
        return source.get(key, global_config.get(key, default))

    platform_os = platform_component('docker_platform_os', 'linux')
    platform_arch = platform_component('docker_platform_arch', 'amd64')
    if platform_filter_enabled and (platform_os, platform_arch) != ('linux', 'amd64'):
        raise ValueError(
            'docker_depth_experiment platform filtering supports only linux/amd64'
        )

    configured_candidate_counts = []
    if 'docker_platform_candidate_tags' in global_config:
        configured_candidate_counts.append((
            global_config['docker_platform_candidate_tags'],
            'global.docker_platform_candidate_tags',
        ))
    if 'docker_platform_candidate_tags' in source:
        configured_candidate_counts.append((
            source['docker_platform_candidate_tags'],
            'sources.dockerhub.docker_platform_candidate_tags',
        ))
    for value, name in configured_candidate_counts:
        _strict_config_integer(value, name, 1, 100)
    candidate_tags = source.get(
        'docker_platform_candidate_tags',
        global_config.get('docker_platform_candidate_tags', 20),
    )
    candidate_tags = _strict_config_integer(
        candidate_tags, 'docker_platform_candidate_tags', 1, 100,
    )
    if candidate_tags < deep_images:
        raise ValueError(
            'docker_platform_candidate_tags must be at least the configured deep image depth'
        )

    for key in (
        'docker_repository_refresh_interval_sec',
        'docker_repository_refresh_max_per_cycle',
    ):
        for owner, name in ((global_config, 'global'), (source, 'sources.dockerhub')):
            if key in owner:
                _strict_config_integer(owner[key], f'{name}.{key}')
    refresh_max = source.get(
        'docker_repository_refresh_max_per_cycle',
        global_config.get('docker_repository_refresh_max_per_cycle', 0),
    )
    if enabled and refresh_max != 0:
        raise ValueError(
            'docker_depth_experiment requires '
            'docker_repository_refresh_max_per_cycle=0'
        )

    database_url = global_config.get('database_url')
    if database_url not in (None, ''):
        if not isinstance(database_url, str) or not _POSTGRES_URL_RE.match(database_url):
            raise ValueError(
                'docker_depth_experiment collection requires a PostgreSQL database_url when configured'
            )
        if managed_postgres is None:
            managed_postgres = True
    if managed_postgres is not None and not isinstance(managed_postgres, bool):
        raise ValueError('managed_postgres validation authority must be boolean or None')
    configured_final_cutover = source.get(
        'sync_file_queues', global_config.get('sync_file_queues', True),
    ) is False
    if final_cutover is None:
        final_cutover = configured_final_cutover
    elif not isinstance(final_cutover, bool):
        raise ValueError('final_cutover validation authority must be boolean or None')
    if managed_postgres is False:
        raise ValueError(
            'docker_depth_experiment collection requires managed PostgreSQL'
        )
    if not configured_final_cutover or final_cutover is not True:
        raise ValueError(
            'docker_depth_experiment collection requires PostgreSQL final cutover'
        )
    if source.get('mode') != 'search':
        raise ValueError(
            'docker_depth_experiment collection requires Docker Hub search mode'
        )
    if source.get('require_digest') is not True:
        raise ValueError(
            'docker_depth_experiment collection requires require_digest=true'
        )

    canonical_experiment = {
        'experiment_key': experiment_key,
        'enabled': enabled,
        'queries': list(queries),
        'repositories_per_query': repositories_per_query,
        'shallow_images_per_repository': shallow_images,
        'deep_repositories_per_query': deep_repositories,
        'deep_images_per_repository': deep_images,
        'target_limit': target_limit,
        'selector_version': selector_version,
    }
    source['docker_depth_experiment'] = canonical_experiment
    ordered_query_hash = canonical_ordered_query_hash(queries)
    selector_hash = canonical_selector_hash(selector_version)
    semantic_experiment = {
        key: value for key, value in canonical_experiment.items()
        if key != 'enabled'
    }
    config_hash = _canonical_sha256({
        'collection_generation': DOCKER_DEPTH_COLLECTION_GENERATION,
        'discovery_policies': list(effective_policies),
        'experiment': semantic_experiment,
        'mode': source.get('mode'),
        'ordinary_images_per_repository': image_depth,
        'platform': {
            'architecture': platform_arch,
            'candidate_tags': candidate_tags,
            'filter_enabled': platform_filter_enabled,
            'os': platform_os,
        },
        'require_digest': source.get('require_digest'),
        'schema': 'docker-depth-experiment-v3',
    })
    experiment = DockerDepthExperimentConfig(
        experiment_key=experiment_key,
        enabled=enabled,
        collection_generation=DOCKER_DEPTH_COLLECTION_GENERATION,
        queries=queries,
        repositories_per_query=repositories_per_query,
        shallow_images_per_repository=shallow_images,
        deep_repositories_per_query=deep_repositories,
        deep_images_per_repository=deep_images,
        target_limit=target_limit,
        selector_version=selector_version,
        theoretical_max_targets=theoretical_max,
        ordered_query_hash=ordered_query_hash,
        config_hash=config_hash,
        selector_hash=selector_hash,
    )
    return ValidatedDockerDepthConfig(
        normalized_config=normalized,
        docker_images_per_repository=image_depth,
        experiment=experiment,
        ordered_query_hash=ordered_query_hash,
        config_hash=config_hash,
        selector_hash=selector_hash,
    )


def _strict_positive_int(value, name, maximum=None):
    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
        raise ValueError(f'{name} must be a positive integer')
    if maximum is not None and value > maximum:
        raise ValueError(f'{name} exceeds its {maximum} bound')
    return value


def _strict_nonnegative_int(value, name):
    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
        raise ValueError(f'{name} must be a non-negative integer')
    return value


def _valid_sha256(value):
    return bool(re.fullmatch(r'[a-f0-9]{64}', str(value or '')))


def _docker_depth_authority(experiment, provenance_policy_sha256):
    if experiment is None:
        raise ValueError('Docker depth experiment authority is unavailable')
    queries = tuple(getattr(experiment, 'queries', ()))
    if (
        len(queries) != DOCKER_DEPTH_QUERY_COUNT
        or len(set(queries)) != DOCKER_DEPTH_QUERY_COUNT
        or any(not isinstance(query, str) or not query or query != query.strip()
               for query in queries)
    ):
        raise ValueError('Docker depth planning requires all 61 unique ordered queries')
    ordered_queries_sha256 = str(getattr(experiment, 'ordered_query_hash', '') or '')
    if ordered_queries_sha256 != canonical_ordered_query_hash(queries):
        raise ValueError('Docker depth ordered-query hash conflicts')
    selector_version = str(getattr(experiment, 'selector_version', '') or '')
    selector_sha256 = str(getattr(experiment, 'selector_hash', '') or '')
    if (
        selector_version not in _DOCKER_EXPERIMENT_PROFILES
        or selector_sha256 != canonical_selector_hash(selector_version)
    ):
        raise ValueError('Docker depth selector authority conflicts')
    config_sha256 = str(getattr(experiment, 'config_hash', '') or '')
    provenance_policy_sha256 = str(provenance_policy_sha256 or '')
    if not _valid_sha256(config_sha256) or not _valid_sha256(provenance_policy_sha256):
        raise ValueError('Docker depth configuration or provenance policy hash is invalid')
    profile = reviewed_docker_experiment_profile(selector_version)
    fixed = (
        (getattr(experiment, 'repositories_per_query', None),
         profile['repositories_per_query']),
        (getattr(experiment, 'shallow_images_per_repository', None),
         profile['shallow_images_per_repository']),
        (getattr(experiment, 'deep_repositories_per_query', None),
         profile['deep_repositories_per_query']),
        (getattr(experiment, 'deep_images_per_repository', None),
         profile['images_per_repository']),
        (getattr(experiment, 'target_limit', None), profile['target_limit']),
    )
    if any(actual != expected for actual, expected in fixed):
        raise ValueError('Docker depth planning limits conflict with the reviewed experiment')
    theoretical_max = profile['theoretical_max_targets']
    if getattr(experiment, 'theoretical_max_targets', None) != theoretical_max:
        raise ValueError('Docker depth theoretical target capacity conflicts')
    experiment_key = _strict_identifier(
        getattr(experiment, 'experiment_key', None), 'experiment_key',
    )
    collection_generation = str(
        getattr(experiment, 'collection_generation', '') or ''
    )
    if collection_generation != DOCKER_DEPTH_COLLECTION_GENERATION:
        raise ValueError('Docker depth collection generation authority conflicts')
    return {
        'experiment_key': experiment_key,
        'source': 'dockerhub',
        'collection_generation': collection_generation,
        'queries': queries,
        'config_sha256': config_sha256,
        'ordered_queries_sha256': ordered_queries_sha256,
        'selector_version': selector_version,
        'selector_sha256': selector_sha256,
        'provenance_policy_sha256': provenance_policy_sha256,
        'query_count': DOCKER_DEPTH_QUERY_COUNT,
        'repositories_per_query': profile['repositories_per_query'],
        'images_per_repository': profile['images_per_repository'],
        'target_limit': profile['target_limit'],
        'theoretical_max_targets': theoretical_max,
    }


def docker_depth_resolver_authority(experiment, provenance_policy_sha256):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    enabled = getattr(experiment, 'enabled', None)
    if not isinstance(enabled, bool):
        raise ValueError('Docker depth resolver enabled authority is invalid')
    return {**authority, 'enabled': enabled}


def _cohort_plan_document(authority, planned_queries):
    round_robin = []
    by_ordinal = {
        item['query_ordinal']: item for item in planned_queries
    }
    for repository_rank in range(1, authority['repositories_per_query'] + 1):
        for query_ordinal in range(authority['query_count']):
            query_plan = by_ordinal[query_ordinal]
            if repository_rank > len(query_plan['repositories']):
                continue
            repository = query_plan['repositories'][repository_rank - 1]
            round_robin.append({
                'query_ordinal': query_ordinal,
                'repository_rank': repository_rank,
                'repository_queue_id': repository['repository_queue_id'],
            })
    return {
        'schema': 2,
        'type': DOCKER_DEPTH_COHORT_PLAN_TYPE,
        'experiment_key': authority['experiment_key'],
        'source': authority['source'],
        'collection_generation': authority['collection_generation'],
        'config_sha256': authority['config_sha256'],
        'ordered_queries_sha256': authority['ordered_queries_sha256'],
        'selector_version': authority['selector_version'],
        'selector_sha256': authority['selector_sha256'],
        'provenance_policy_sha256': authority['provenance_policy_sha256'],
        'query_count': authority['query_count'],
        'repositories_per_query': authority['repositories_per_query'],
        'images_per_repository': authority['images_per_repository'],
        'target_limit': authority['target_limit'],
        'theoretical_max_targets': authority['theoretical_max_targets'],
        'queries': planned_queries,
        'repository_round_robin': round_robin,
    }


def build_docker_depth_cohort_plan(
    experiment, provenance_policy_sha256, candidates_by_query,
):
    """Build the immutable cohort from already fenced fresh-candidate rows."""
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    if not isinstance(candidates_by_query, dict) or set(candidates_by_query) != set(
        authority['queries']
    ):
        raise ValueError('Docker depth candidates must cover exactly all 61 ordered queries')
    normalized_by_query = []
    for query_ordinal, query in enumerate(authority['queries']):
        values = candidates_by_query[query]
        if isinstance(values, (str, bytes)):
            raise ValueError('Docker depth query candidates are invalid')
        try:
            values = list(values)
        except TypeError:
            raise ValueError('Docker depth query candidates are invalid') from None
        normalized = []
        seen = set()
        for raw in values:
            if not isinstance(raw, dict):
                raw = dict(raw)
            queue_id = _strict_positive_int(
                raw.get('repository_queue_id'), 'repository_queue_id',
            )
            if queue_id in seen:
                raise ValueError('Docker depth query candidates contain a duplicate repository')
            seen.add(queue_id)
            normalized.append({
                'repository_queue_id': queue_id,
                'eligibility_page_id': _strict_positive_int(
                    raw.get('eligibility_page_id'), 'eligibility_page_id',
                ),
                'best_search_rank': _strict_positive_int(
                    raw.get('best_search_rank'), 'best_search_rank',
                ),
                'valid_distinct_graph_count': _strict_nonnegative_int(
                    raw.get('valid_distinct_graph_count', 0),
                    'valid_distinct_graph_count',
                ),
            })
        normalized.sort(key=lambda item: (
            item['best_search_rank'], item['repository_queue_id'],
        ))
        normalized_by_query.append(normalized)

    if authority['selector_version'] == DOCKER_DEPTH_SELECTOR_VERSION:
        selected_by_query = [
            values[:DOCKER_DEPTH_REPOSITORIES_PER_QUERY]
            for values in normalized_by_query
        ]
    else:
        selected_by_query = [[] for _query in authority['queries']]
        cursors = [0] * len(selected_by_query)
        seen_queue_ids = set()
        selected_count = 0
        while selected_count < authority['target_limit']:
            progressed = False
            for ordinal, values in enumerate(normalized_by_query):
                if len(selected_by_query[ordinal]) >= authority['repositories_per_query']:
                    continue
                while (
                    cursors[ordinal] < len(values)
                    and values[cursors[ordinal]]['repository_queue_id'] in seen_queue_ids
                ):
                    cursors[ordinal] += 1
                if cursors[ordinal] >= len(values):
                    continue
                candidate = values[cursors[ordinal]]
                cursors[ordinal] += 1
                selected_by_query[ordinal].append(candidate)
                seen_queue_ids.add(candidate['repository_queue_id'])
                selected_count += 1
                progressed = True
                if selected_count == authority['target_limit']:
                    break
            if not progressed:
                break
        if selected_count != authority['target_limit']:
            raise ValueError('Docker rank1 breadth cohort cannot fill its exact target limit')

    planned_queries = []
    for query_ordinal, query in enumerate(authority['queries']):
        selected = selected_by_query[query_ordinal]
        deep = min(selected, key=lambda item: (
            -item['valid_distinct_graph_count'],
            item['best_search_rank'],
            item['repository_queue_id'],
        )) if selected else None
        repositories = []
        for repository_rank, item in enumerate(selected, 1):
            repositories.append({
                'repository_queue_id': item['repository_queue_id'],
                'eligibility_page_id': item['eligibility_page_id'],
                'repository_rank': repository_rank,
                'is_deep_probe': bool(
                    deep and item['repository_queue_id'] == deep['repository_queue_id']
                ),
            })
        planned_queries.append({
            'query_ordinal': query_ordinal,
            'query': query,
            'query_sha256': _canonical_sha256(query),
            'selected_repository_count': len(repositories),
            'repositories': repositories,
        })
    if authority['selector_version'] == DOCKER_RANK1_BREADTH_SELECTOR_VERSION:
        queue_ids = [
            repository['repository_queue_id']
            for query in planned_queries for repository in query['repositories']
        ]
        if len(queue_ids) != len(set(queue_ids)):
            raise ValueError(
                'Docker rank1 breadth cohort contains a duplicate physical repository'
            )
    return _cohort_plan_document(authority, planned_queries)


def canonical_docker_depth_plan_hash(plan):
    if not isinstance(plan, dict) or plan.get('type') != DOCKER_DEPTH_COHORT_PLAN_TYPE:
        raise ValueError('Docker depth cohort plan type is invalid')
    return _canonical_sha256(plan)


def _validate_docker_depth_cohort_plan(
    manifest, experiment=None, provenance_policy_sha256=None,
):
    """Validate the immutable plan carried by a reviewed cohort manifest."""
    expected_keys = {
        'schema', 'type', 'experiment_key', 'source', 'collection_generation',
        'config_sha256', 'ordered_queries_sha256', 'selector_version',
        'selector_sha256', 'provenance_policy_sha256', 'query_count',
        'repositories_per_query', 'images_per_repository', 'target_limit',
        'theoretical_max_targets', 'queries', 'repository_round_robin',
    }
    if (
        not isinstance(manifest, dict)
        or set(manifest) != expected_keys
        or type(manifest.get('schema')) is not int
        or manifest.get('schema') != 2
        or manifest.get('type') != DOCKER_DEPTH_COHORT_PLAN_TYPE
    ):
        raise ValueError('Docker depth cohort manifest shape is invalid')
    if (
        manifest.get('source') != 'dockerhub'
        or manifest.get('collection_generation') != DOCKER_DEPTH_COLLECTION_GENERATION
        or manifest.get('selector_version') not in _DOCKER_EXPERIMENT_PROFILES
        or manifest.get('selector_sha256')
        != canonical_selector_hash(manifest.get('selector_version'))
        or any(not _valid_sha256(manifest.get(name)) for name in (
            'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
            'provenance_policy_sha256',
        ))
    ):
        raise ValueError('Docker depth cohort manifest authority is invalid')
    _strict_identifier(manifest.get('experiment_key'), 'experiment_key')
    profile = reviewed_docker_experiment_profile(manifest['selector_version'])
    fixed = {
        'query_count': profile['query_count'],
        'repositories_per_query': profile['repositories_per_query'],
        'images_per_repository': profile['images_per_repository'],
        'target_limit': profile['target_limit'],
        'theoretical_max_targets': profile['theoretical_max_targets'],
    }
    if any(type(manifest.get(name)) is not int or manifest[name] != value
           for name, value in fixed.items()):
        raise ValueError('Docker depth cohort manifest limits conflict')
    raw_queries = manifest.get('queries')
    if not isinstance(raw_queries, list) or len(raw_queries) != fixed['query_count']:
        raise ValueError('Docker depth cohort manifest query coverage is incomplete')
    planned_queries = []
    queries = []
    global_queue_ids = set()
    for ordinal, raw_query in enumerate(raw_queries):
        if not isinstance(raw_query, dict) or set(raw_query) != {
            'query_ordinal', 'query', 'query_sha256',
            'selected_repository_count', 'repositories',
        }:
            raise ValueError('Docker depth cohort manifest query shape is invalid')
        query = raw_query.get('query')
        if (
            type(raw_query.get('query_ordinal')) is not int
            or raw_query['query_ordinal'] != ordinal
            or not isinstance(query, str)
            or not query
            or query != query.strip()
            or raw_query.get('query_sha256') != _canonical_sha256(query)
        ):
            raise ValueError('Docker depth cohort manifest query identity conflicts')
        raw_repositories = raw_query.get('repositories')
        selected_repository_count = raw_query.get('selected_repository_count')
        if (
            not isinstance(raw_repositories, list)
            or type(selected_repository_count) is not int
            or not 0 <= selected_repository_count <= fixed['repositories_per_query']
            or len(raw_repositories) != selected_repository_count
        ):
            raise ValueError('Docker depth cohort manifest membership count conflicts')
        repositories = []
        queue_ids = set()
        for rank, raw_repository in enumerate(raw_repositories, 1):
            if not isinstance(raw_repository, dict) or set(raw_repository) != {
                'repository_queue_id', 'eligibility_page_id', 'repository_rank',
                'is_deep_probe',
            }:
                raise ValueError('Docker depth cohort manifest membership shape is invalid')
            queue_id = _strict_positive_int(
                raw_repository.get('repository_queue_id'), 'repository_queue_id',
            )
            if queue_id in queue_ids:
                raise ValueError('Docker depth cohort manifest membership is duplicated')
            queue_ids.add(queue_id)
            if (
                manifest['selector_version'] == DOCKER_RANK1_BREADTH_SELECTOR_VERSION
                and queue_id in global_queue_ids
            ):
                raise ValueError('Docker rank1 breadth cohort physical membership is duplicated')
            global_queue_ids.add(queue_id)
            if (
                type(raw_repository.get('repository_rank')) is not int
                or raw_repository['repository_rank'] != rank
                or type(raw_repository.get('is_deep_probe')) is not bool
            ):
                raise ValueError('Docker depth cohort manifest rank identity conflicts')
            repositories.append({
                'repository_queue_id': queue_id,
                'eligibility_page_id': _strict_positive_int(
                    raw_repository.get('eligibility_page_id'), 'eligibility_page_id',
                ),
                'repository_rank': rank,
                'is_deep_probe': raw_repository['is_deep_probe'],
            })
        expected_deep_count = 1 if repositories else 0
        if sum(int(item['is_deep_probe']) for item in repositories) != expected_deep_count:
            raise ValueError('Docker depth cohort manifest deep membership conflicts')
        queries.append(query)
        planned_queries.append({
            'query_ordinal': ordinal,
            'query': query,
            'query_sha256': _canonical_sha256(query),
            'selected_repository_count': selected_repository_count,
            'repositories': repositories,
        })
    if len(set(queries)) != fixed['query_count']:
        raise ValueError('Docker depth cohort manifest queries are duplicated')
    if (
        manifest['selector_version'] == DOCKER_RANK1_BREADTH_SELECTOR_VERSION
        and len(global_queue_ids) != fixed['target_limit']
    ):
        raise ValueError('Docker rank1 breadth cohort target count conflicts')
    if manifest['ordered_queries_sha256'] != canonical_ordered_query_hash(queries):
        raise ValueError('Docker depth cohort manifest ordered-query hash conflicts')
    authority = {
        'experiment_key': manifest['experiment_key'],
        'source': manifest['source'],
        'collection_generation': manifest['collection_generation'],
        'queries': tuple(queries),
        'config_sha256': manifest['config_sha256'],
        'ordered_queries_sha256': manifest['ordered_queries_sha256'],
        'selector_version': manifest['selector_version'],
        'selector_sha256': manifest['selector_sha256'],
        'provenance_policy_sha256': manifest['provenance_policy_sha256'],
        **fixed,
    }
    if experiment is not None:
        expected_authority = _docker_depth_authority(
            experiment,
            provenance_policy_sha256 or manifest['provenance_policy_sha256'],
        )
        if authority != expected_authority:
            raise ValueError('Docker depth cohort manifest authority drifted')
    canonical = _cohort_plan_document(authority, planned_queries)
    if canonical != manifest:
        raise ValueError('Docker depth cohort manifest is not canonical')
    normalized = copy.deepcopy(canonical)
    return normalized, canonical_docker_depth_plan_hash(normalized)


def _cohort_provenance_snapshot(authority, candidates_by_query):
    if not isinstance(candidates_by_query, dict) or set(candidates_by_query) != set(
        authority['queries']
    ):
        raise ValueError('Docker depth candidates must cover exactly all 61 ordered queries')
    queries = []
    for query_ordinal, query in enumerate(authority['queries']):
        values = candidates_by_query[query]
        if isinstance(values, (str, bytes)):
            raise ValueError('Docker depth query candidates are invalid')
        try:
            values = list(values)
        except TypeError:
            raise ValueError('Docker depth query candidates are invalid') from None
        normalized = []
        seen = set()
        for raw in values:
            if not isinstance(raw, dict):
                raw = dict(raw)
            queue_id = _strict_positive_int(
                raw.get('repository_queue_id'), 'repository_queue_id',
            )
            if queue_id in seen:
                raise ValueError('Docker depth query candidates contain a duplicate repository')
            seen.add(queue_id)
            normalized.append({
                'repository_queue_id': queue_id,
                'eligibility_page_id': _strict_positive_int(
                    raw.get('eligibility_page_id'), 'eligibility_page_id',
                ),
                'best_search_rank': _strict_positive_int(
                    raw.get('best_search_rank'), 'best_search_rank',
                ),
                'valid_distinct_graph_count': _strict_nonnegative_int(
                    raw.get('valid_distinct_graph_count', 0),
                    'valid_distinct_graph_count',
                ),
            })
        normalized.sort(key=lambda item: (
            item['best_search_rank'], item['repository_queue_id'],
        ))
        selected = normalized[:authority['repositories_per_query']]
        queries.append({
            'query_ordinal': query_ordinal,
            'query_sha256': _canonical_sha256(query),
            'selected_repository_count': len(selected),
            'repositories': selected,
        })
    return {
        'schema': 2,
        'type': 'truf-docker-depth-cohort-provenance-snapshot-v2',
        'collection_generation': authority['collection_generation'],
        'config_sha256': authority['config_sha256'],
        'ordered_queries_sha256': authority['ordered_queries_sha256'],
        'selector_sha256': authority['selector_sha256'],
        'provenance_policy_sha256': authority['provenance_policy_sha256'],
        'queries': queries,
    }


def build_docker_depth_cohort_manifest(
    experiment, provenance_policy_sha256, candidates_by_query,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    plan = build_docker_depth_cohort_plan(
        experiment, provenance_policy_sha256, candidates_by_query,
    )
    snapshot = _cohort_provenance_snapshot(authority, candidates_by_query)
    manifest = {
        'schema': 2,
        'type': DOCKER_DEPTH_COHORT_MANIFEST_TYPE,
        'version': 2,
        'experiment_key': authority['experiment_key'],
        'source': authority['source'],
        'collection_generation': authority['collection_generation'],
        'collection_generation_sha256': _canonical_sha256(
            authority['collection_generation']
        ),
        'config_sha256': authority['config_sha256'],
        'ordered_queries_sha256': authority['ordered_queries_sha256'],
        'selector_version': authority['selector_version'],
        'selector_sha256': authority['selector_sha256'],
        'provenance_policy_sha256': authority['provenance_policy_sha256'],
        'provenance_snapshot_sha256': _canonical_sha256(snapshot),
        'query_count': authority['query_count'],
        'repository_count': sum(
            item['selected_repository_count'] for item in plan['queries']
        ),
        'plan_sha256': canonical_docker_depth_plan_hash(plan),
        'plan': plan,
    }
    return validate_docker_depth_cohort_manifest(
        manifest, experiment, provenance_policy_sha256,
    )[0]


def validate_docker_depth_cohort_manifest(
    manifest, experiment=None, provenance_policy_sha256=None,
):
    expected_keys = {
        'schema', 'type', 'version', 'experiment_key', 'source',
        'collection_generation', 'collection_generation_sha256',
        'config_sha256', 'ordered_queries_sha256', 'selector_version',
        'selector_sha256', 'provenance_policy_sha256',
        'provenance_snapshot_sha256', 'query_count', 'repository_count',
        'plan_sha256', 'plan',
    }
    if (
        not isinstance(manifest, dict)
        or set(manifest) != expected_keys
        or type(manifest.get('schema')) is not int
        or manifest.get('schema') != 2
        or type(manifest.get('version')) is not int
        or manifest.get('version') != 2
        or manifest.get('type') != DOCKER_DEPTH_COHORT_MANIFEST_TYPE
    ):
        raise ValueError('Docker depth cohort review manifest shape is invalid')
    plan, plan_sha256 = _validate_docker_depth_cohort_plan(
        manifest.get('plan'), experiment, provenance_policy_sha256,
    )
    for name in (
        'collection_generation_sha256', 'config_sha256',
        'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'provenance_snapshot_sha256', 'plan_sha256',
    ):
        if not _valid_sha256(manifest.get(name)):
            raise ValueError('Docker depth cohort review manifest contains an invalid hash')
    if (
        manifest['experiment_key'] != plan['experiment_key']
        or manifest['source'] != plan['source']
        or manifest['collection_generation'] != plan['collection_generation']
        or manifest['collection_generation_sha256']
        != _canonical_sha256(plan['collection_generation'])
        or manifest['config_sha256'] != plan['config_sha256']
        or manifest['ordered_queries_sha256'] != plan['ordered_queries_sha256']
        or manifest['selector_version'] != plan['selector_version']
        or manifest['selector_sha256'] != plan['selector_sha256']
        or manifest['provenance_policy_sha256'] != plan['provenance_policy_sha256']
        or type(manifest.get('query_count')) is not int
        or manifest['query_count'] != plan['query_count']
        or type(manifest.get('repository_count')) is not int
        or manifest['repository_count']
        != sum(item['selected_repository_count'] for item in plan['queries'])
        or manifest['plan_sha256'] != plan_sha256
    ):
        raise ValueError('Docker depth cohort review manifest evidence conflicts')
    normalized = copy.deepcopy(manifest)
    normalized['plan'] = plan
    if normalized != manifest:
        raise ValueError('Docker depth cohort review manifest is not canonical')
    return normalized, _canonical_sha256(normalized)


def _require_postgres_experiment_db(db, operation):
    conn = getattr(db, 'conn', None)
    if not conn or not getattr(conn, 'is_postgres', False):
        raise RuntimeError(f'{operation} requires managed PostgreSQL')
    return conn


def _experiment_identity_matches(row, authority):
    expected = {
        'experiment_key': authority['experiment_key'],
        'source': authority['source'],
        'collection_generation': authority['collection_generation'],
        'config_sha256': authority['config_sha256'],
        'ordered_queries_sha256': authority['ordered_queries_sha256'],
        'selector_version': authority['selector_version'],
        'selector_sha256': authority['selector_sha256'],
        'provenance_policy_sha256': authority['provenance_policy_sha256'],
        'query_count': authority['query_count'],
        'repositories_per_query': authority['repositories_per_query'],
        'images_per_repository': authority['images_per_repository'],
        'target_limit': authority['target_limit'],
    }
    return all(
        (int(row[name]) if isinstance(value, int) else str(row[name])) == value
        for name, value in expected.items()
    )


def _stored_cohort_plan(conn, experiment_row, authority):
    experiment_id = int(experiment_row['id'])
    query_rows = conn.execute(
        '''SELECT query_ordinal, query, query_sha256,
                  required_repository_count, selected_repository_count
           FROM docker_depth_experiment_queries
           WHERE experiment_id = ? ORDER BY query_ordinal''',
        (experiment_id,),
    ).fetchall()
    repository_rows = conn.execute(
        '''SELECT query_ordinal, repository_queue_id, eligibility_page_id,
                  repository_rank, planned_is_deep_probe
           FROM docker_depth_experiment_repositories
           WHERE experiment_id = ? ORDER BY query_ordinal, repository_rank''',
        (experiment_id,),
    ).fetchall()
    expected_repository_count = sum(
        int(row['selected_repository_count']) for row in query_rows
    ) if len(query_rows) == authority['query_count'] else -1
    if (
        len(query_rows) != authority['query_count']
        or len(repository_rows) != expected_repository_count
    ):
        raise RuntimeError('Docker depth persisted cohort is incomplete')
    repositories_by_query = {
        ordinal: [] for ordinal in range(authority['query_count'])
    }
    for row in repository_rows:
        ordinal = int(row['query_ordinal'])
        if ordinal not in repositories_by_query:
            raise RuntimeError('Docker depth persisted repository ordinal is invalid')
        repositories_by_query[ordinal].append({
            'repository_queue_id': int(row['repository_queue_id']),
            'eligibility_page_id': int(row['eligibility_page_id']),
            'repository_rank': int(row['repository_rank']),
            'is_deep_probe': bool(row['planned_is_deep_probe']),
        })
    planned_queries = []
    for ordinal, row in enumerate(query_rows):
        repositories = repositories_by_query[ordinal]
        selected_repository_count = int(row['selected_repository_count'])
        if (
            int(row['query_ordinal']) != ordinal
            or str(row['query']) != authority['queries'][ordinal]
            or str(row['query_sha256']) != _canonical_sha256(authority['queries'][ordinal])
            or int(row['required_repository_count']) != authority['repositories_per_query']
            or not 0 <= selected_repository_count <= authority['repositories_per_query']
            or len(repositories) != selected_repository_count
            or [item['repository_rank'] for item in repositories]
               != list(range(1, selected_repository_count + 1))
            or sum(int(item['is_deep_probe']) for item in repositories)
               != (1 if selected_repository_count else 0)
        ):
            raise RuntimeError('Docker depth persisted cohort identity conflicts')
        planned_queries.append({
            'query_ordinal': ordinal,
            'query': authority['queries'][ordinal],
            'query_sha256': str(row['query_sha256']),
            'selected_repository_count': selected_repository_count,
            'repositories': repositories,
        })
    return _cohort_plan_document(authority, planned_queries)


def _fresh_cohort_candidates(conn, authority, include_experiment_id=None):
    candidates_by_query = {}
    coverage = []
    breadth_profile = (
        authority['selector_version'] == DOCKER_RANK1_BREADTH_SELECTOR_VERSION
    )
    candidate_limit = 3000 if breadth_profile else authority['repositories_per_query']
    if breadth_profile:
        policy_filter = '''AND NOT EXISTS (
                     SELECT 1
                       FROM target_queue_policy_events event
                       LEFT JOIN docker_depth_experiments prior
                         ON prior.id = event.experiment_id
                      WHERE event.queue_id = queue.id
                        AND (
                            prior.id IS NULL OR prior.state <> 'released'
                            OR event.source <> queue.source
                            OR event.platform <> queue.platform
                            OR event.query <> queue.query
                            OR event.config_sha256 <> prior.config_sha256
                            OR event.policy_sha256 <> prior.provenance_policy_sha256
                            OR (event.action = 'cold' AND NOT EXISTS (
                                SELECT 1 FROM target_queue_policy_events reverse_event
                                 WHERE reverse_event.reverses_event_id = event.id
                                   AND reverse_event.action = 'reactivate'
                                   AND reverse_event.experiment_id = event.experiment_id
                                   AND reverse_event.queue_id = event.queue_id
                            ))
                            OR (event.action = 'reactivate' AND NOT EXISTS (
                                SELECT 1 FROM target_queue_policy_events cold_event
                                 WHERE cold_event.id = event.reverses_event_id
                                   AND cold_event.action = 'cold'
                                   AND cold_event.experiment_id = event.experiment_id
                                   AND cold_event.queue_id = event.queue_id
                            ))
                        )
                 )'''
    else:
        policy_filter = '''AND NOT EXISTS (
                     SELECT 1 FROM target_queue_policy_events event
                      WHERE event.queue_id = queue.id
                 )'''
    if include_experiment_id is None:
        member_filter = '''AND NOT EXISTS (
                     SELECT 1 FROM docker_depth_experiment_repositories member
                     WHERE member.repository_queue_id = queue.id
                 )'''
        member_params = ()
    else:
        member_filter = '''AND NOT EXISTS (
                     SELECT 1 FROM docker_depth_experiment_repositories member
                     WHERE member.repository_queue_id = queue.id
                       AND member.experiment_id <> ?
                 )'''
        member_params = (int(include_experiment_id),)
    for query_ordinal, query in enumerate(authority['queries']):
        candidates = conn.execute(
            f'''SELECT provenance.repository_queue_id,
                      MIN(observation.search_rank) AS best_search_rank,
                      MIN(observation.page_id) AS eligibility_page_id,
                      COALESCE((
                          SELECT COUNT(DISTINCT manifest.graph_sha256)
                          FROM docker_image_manifests manifest
                          WHERE manifest.source = queue.source
                            AND manifest.repository = queue.normalized_target
                      ), 0) AS valid_distinct_graph_count
               FROM docker_repository_query_provenance provenance
               JOIN docker_repository_query_observations observation
                 ON observation.source = provenance.source
                AND observation.query = provenance.query
                AND observation.repository_queue_id = provenance.repository_queue_id
               JOIN docker_discovery_pages page ON page.id = observation.page_id
               JOIN docker_discovery_passes discovery_pass ON discovery_pass.id = page.pass_id
               JOIN target_queue queue ON queue.id = provenance.repository_queue_id
               WHERE provenance.source = ? AND provenance.query = ?
                 AND provenance.provenance_kind = 'fresh_page'
                 AND provenance.fresh_coverage_eligible = 1
                 AND provenance.fresh_complete_observation_count > 0
                 AND page.query_ordinal = ? AND page.query = ?
                 AND discovery_pass.source = ? AND discovery_pass.pass_kind = 'deep'
                 AND discovery_pass.collection_generation = ?
                 AND discovery_pass.policy_sha256 = ?
                 AND discovery_pass.ordered_queries_sha256 = ?
                 AND discovery_pass.expected_query_count = ?
                 AND discovery_pass.state = 'complete'
                 AND queue.source = ? AND queue.platform = 'docker'
                 AND queue.status IN ('pending','deferred')
                 AND queue.target_scan_id IS NULL
                 AND queue.target NOT LIKE '%@%' AND queue.normalized_target NOT LIKE '%@%'
                 AND queue.lease_owner IS NULL AND queue.lease_token IS NULL
                 AND queue.claim_batch IS NULL AND queue.leased_at IS NULL
                 AND queue.lease_expires_at IS NULL
                 AND queue.current_result_reservation_id IS NULL
                 AND queue.claim_event_id IS NULL AND queue.resolver_token IS NULL
                 AND COALESCE(queue.resolver_state, '') <> 'resolving'
                 AND NOT EXISTS (SELECT 1 FROM target_scans scan WHERE scan.queue_id = queue.id)
                  {policy_filter}
                 AND NOT EXISTS (
                     SELECT 1 FROM result_reservations reservation
                     WHERE reservation.queue_id = queue.id
                       AND reservation.state IN ('scanning','ready','ingesting','db_committed')
                 )
                 AND NOT EXISTS (
                     SELECT 1 FROM result_reservations reservation
                     JOIN pipeline_quarantine quarantine ON quarantine.reservation_id = reservation.id
                     WHERE reservation.queue_id = queue.id
                 )
                 AND NOT EXISTS (
                     SELECT 1 FROM docker_image_manifests manifest
                     WHERE manifest.target_queue_id = queue.id
                 )
                 AND NOT EXISTS (
                     SELECT 1 FROM docker_image_blob_coverage coverage
                     JOIN docker_content_blobs blob
                       ON blob.digest = coverage.blob_digest
                      AND blob.coverage_policy_sha256 = coverage.coverage_policy_sha256
                     WHERE coverage.queue_id = queue.id
                       AND blob.state IN ('leased','submitted')
                 )
                 {member_filter}
               GROUP BY provenance.repository_queue_id, queue.source, queue.normalized_target
               ORDER BY MIN(observation.search_rank), provenance.repository_queue_id
               LIMIT ?''',
            (
                authority['source'], query, query_ordinal, query,
                authority['source'], authority['collection_generation'],
                authority['provenance_policy_sha256'],
                authority['ordered_queries_sha256'], authority['query_count'],
                authority['source'], *member_params,
                candidate_limit,
            ),
        ).fetchall()
        normalized = [dict(candidate) for candidate in candidates]
        candidates_by_query[query] = normalized
        coverage.append({
            'query_ordinal': query_ordinal,
            'query_sha256': _canonical_sha256(query),
            'eligible_slots': len(normalized),
            'required_slots': authority['repositories_per_query'],
            'eligible_slots_sha256': _canonical_sha256(normalized),
        })
    return candidates_by_query, coverage


def _require_complete_docker_depth_collection_pass(conn, authority):
    row = conn.execute(
        '''SELECT id FROM docker_discovery_passes
           WHERE source = ? AND pass_kind = 'deep'
             AND collection_generation = ? AND policy_sha256 = ?
             AND ordered_queries_sha256 = ? AND expected_query_count = ?
             AND completed_query_count = expected_query_count
             AND state = 'complete' AND completed_at IS NOT NULL
           ORDER BY id LIMIT 1''',
        (
            authority['source'], authority['collection_generation'],
            authority['provenance_policy_sha256'],
            authority['ordered_queries_sha256'], authority['query_count'],
        ),
    ).fetchone()
    if not row:
        raise RuntimeError(
            'Docker depth cohort requires a complete fresh deep discovery pass'
        )
    return int(row['id'])


def summarize_docker_depth_fresh_coverage(
    db, experiment, provenance_policy_sha256,
):
    """Return a query-name-free summary of the current 61-by-10 eligibility gate."""
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    conn = _require_postgres_experiment_db(db, 'Docker depth coverage status')
    candidates_by_query, coverage = _fresh_cohort_candidates(conn, authority)
    complete = sum(
        len(candidates_by_query[query]) >= authority['repositories_per_query']
        for query in authority['queries']
    )
    eligible_slot_histogram = {
        str(slot_count): sum(
            len(candidates_by_query[query]) == slot_count
            for query in authority['queries']
        )
        for slot_count in range(authority['repositories_per_query'] + 1)
    }
    return {
        'query_count': authority['query_count'],
        'complete_query_count': complete,
        'incomplete_query_count': authority['query_count'] - complete,
        'eligible_slot_histogram': eligible_slot_histogram,
        'required_repository_count': (
            authority['query_count'] * authority['repositories_per_query']
        ),
        'eligible_repository_slots': sum(
            len(candidates_by_query[query]) for query in authority['queries']
        ),
        'coverage_sha256': _canonical_sha256({
            'collection_generation': authority['collection_generation'],
            'config_sha256': authority['config_sha256'],
            'ordered_queries_sha256': authority['ordered_queries_sha256'],
            'provenance_policy_sha256': authority['provenance_policy_sha256'],
            'queries': coverage,
            'schema': 1,
            'selector_sha256': authority['selector_sha256'],
            'type': 'truf-docker-depth-fresh-coverage-v1',
        }),
    }


def _cohort_partial_count(conn, experiment_id):
    return int(conn.execute(
        '''SELECT
               (SELECT COUNT(*) FROM docker_depth_experiment_queries
                WHERE experiment_id = ?) +
               (SELECT COUNT(*) FROM docker_depth_experiment_repositories
                WHERE experiment_id = ?) AS count''',
        (experiment_id, experiment_id),
    ).fetchone()['count'])


def _experiment_fence_active(row):
    return any(
        row[name] is not None
        for name in ('fence_owner', 'fence_token', 'fence_expires_at')
    )


def generate_docker_depth_cohort_manifest(
    db, experiment, provenance_policy_sha256,
):
    """Build a deterministic cohort manifest without changing database state."""
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    conn = _require_postgres_experiment_db(db, 'Docker depth cohort review')
    try:
        row = conn.execute(
            'SELECT * FROM docker_depth_experiments WHERE experiment_key = ?',
            (authority['experiment_key'],),
        ).fetchone()
        if row:
            if not _experiment_identity_matches(row, authority):
                raise RuntimeError('Docker depth experiment authority hash drifted')
            if _experiment_fence_active(row):
                raise RuntimeError('Docker depth experiment has an active authority fence')
            if row['plan_sha256'] is not None:
                raise RuntimeError('Docker depth cohort is already persisted')
            if str(row['state']) != 'collecting' or _cohort_partial_count(conn, row['id']):
                raise RuntimeError('Docker depth collecting experiment is not empty')
        _require_complete_docker_depth_collection_pass(conn, authority)
        candidates_by_query, _coverage = _fresh_cohort_candidates(conn, authority)
        manifest = build_docker_depth_cohort_manifest(
            experiment, provenance_policy_sha256, candidates_by_query,
        )
        _require_planned_cohort_current(conn, manifest['plan'], False)
        manifest, manifest_sha256 = validate_docker_depth_cohort_manifest(
            manifest, experiment, provenance_policy_sha256,
        )
        conn.commit()
        return manifest, manifest_sha256
    except Exception:
        conn.rollback()
        raise


def _lock_cohort_manifest_rows(conn, manifest):
    queue_ids = sorted({
        repository['repository_queue_id']
        for query_plan in manifest['plan']['queries']
        for repository in query_plan['repositories']
    })
    if not queue_ids:
        return
    placeholders = ','.join('?' for _ in queue_ids)
    rows = conn.execute(
        f'''SELECT id FROM target_queue WHERE id IN ({placeholders})
            ORDER BY id FOR UPDATE''',
        tuple(queue_ids),
    ).fetchall()
    if [int(row['id']) for row in rows] != queue_ids:
        raise RuntimeError('Docker depth reviewed cohort contains a missing repository')


def _policy_event_audit_sha256(action, manifest_sha256, entry, experiment_id):
    return _canonical_sha256({
        'action': str(action),
        'manifest_sha256': str(manifest_sha256),
        'entry': dict(entry),
        'experiment_id': int(experiment_id),
    })


def _require_released_policy_history(conn, queue_ids):
    grouped = {int(queue_id): [] for queue_id in queue_ids}
    values = sorted(grouped)
    for offset in range(0, len(values), 500):
        chunk = values[offset:offset + 500]
        placeholders = ','.join('?' for _ in chunk)
        rows = conn.execute(
            f'''SELECT event.*, queue.status AS queue_status,
                       queue.source AS queue_source,
                       queue.platform AS queue_platform,
                       queue.query AS queue_query,
                       prior.state AS experiment_state,
                       prior.config_sha256 AS experiment_config_sha256,
                       prior.provenance_policy_sha256 AS experiment_policy_sha256,
                       prior.hold_manifest_sha256 AS experiment_hold_manifest_sha256
                  FROM target_queue_policy_events event
                  JOIN target_queue queue ON queue.id = event.queue_id
                  LEFT JOIN docker_depth_experiments prior
                    ON prior.id = event.experiment_id
                 WHERE event.queue_id IN ({placeholders})
                 ORDER BY event.queue_id, event.id''',
            tuple(chunk),
        ).fetchall()
        for row in rows:
            grouped[int(row['queue_id'])].append(row)

    for queue_id, events in grouped.items():
        if not events:
            continue
        by_id = {int(event['id']): event for event in events}
        cold_events = [event for event in events if event['action'] == 'cold']
        reverse_events = [event for event in events if event['action'] == 'reactivate']
        if len(cold_events) != len(reverse_events):
            raise RuntimeError('Docker breadth candidate policy history is incomplete')
        used_reverse_ids = set()
        for cold in cold_events:
            reverses = [
                event for event in reverse_events
                if int(event['reverses_event_id'] or 0) == int(cold['id'])
            ]
            if len(reverses) != 1:
                raise RuntimeError('Docker breadth candidate policy history is ambiguous')
            reverse = reverses[0]
            used_reverse_ids.add(int(reverse['id']))
            experiment_id = int(cold['experiment_id'] or 0)
            shared_conflict = any(
                event['experiment_id'] is None
                or int(event['experiment_id']) != experiment_id
                or int(event['queue_id']) != queue_id
                or str(event['source']) != str(event['queue_source'])
                or str(event['platform']) != str(event['queue_platform'])
                or str(event['query']) != str(event['queue_query'])
                or str(event['experiment_state']) != 'released'
                or str(event['config_sha256'])
                   != str(event['experiment_config_sha256'])
                or str(event['policy_sha256'])
                   != str(event['experiment_policy_sha256'])
                for event in (cold, reverse)
            )
            if (
                shared_conflict
                or cold['reverses_event_id'] is not None
                or str(cold['reason_code']) not in (
                    DOCKER_DEPTH_HOLD_REASON, DOCKER_DEPTH_DYNAMIC_HOLD_REASON,
                )
                or str(cold['manifest_sha256'])
                   != str(cold['experiment_hold_manifest_sha256'])
                or str(cold['prior_status']) not in ('pending', 'deferred')
                or str(cold['next_status']) != 'cold'
                or str(reverse['reason_code']) != DOCKER_DEPTH_RELEASE_REASON
                or str(reverse['prior_status']) != 'cold'
                or str(reverse['next_status']) != str(cold['prior_status'])
                or str(reverse['queue_status']) != str(reverse['next_status'])
            ):
                raise RuntimeError('Docker breadth candidate policy history conflicts')
            cold_entry = {
                'queue_id': queue_id,
                'source': str(cold['source']),
                'platform': str(cold['platform']),
                'query': str(cold['query']),
                'prior_status': str(cold['prior_status']),
                'prior_updated_at': str(cold['prior_updated_at']),
            }
            reverse_entry = {
                'queue_id': queue_id,
                'source': str(reverse['source']),
                'platform': str(reverse['platform']),
                'query': str(reverse['query']),
                'cold_event_id': int(cold['id']),
                'restore_status': str(reverse['next_status']),
                'prior_updated_at': str(reverse['prior_updated_at']),
            }
            if (
                str(cold['review_audit_sha256'])
                != _policy_event_audit_sha256(
                    'cold', cold['manifest_sha256'], cold_entry, experiment_id,
                )
                or str(reverse['review_audit_sha256'])
                != _policy_event_audit_sha256(
                    'reactivate', reverse['manifest_sha256'], reverse_entry,
                    experiment_id,
                )
            ):
                raise RuntimeError('Docker breadth candidate policy audit conflicts')
        if len(used_reverse_ids) != len(reverse_events) or any(
            int(event['reverses_event_id'] or 0) not in by_id
            for event in reverse_events
        ):
            raise RuntimeError('Docker breadth candidate policy reversal conflicts')


def _require_planned_cohort_current(conn, manifest, lock_rows):
    queue_ids = sorted({
        repository['repository_queue_id']
        for query_plan in manifest['queries']
        for repository in query_plan['repositories']
    })
    if not queue_ids:
        return
    placeholders = ','.join('?' for _ in queue_ids)
    lock_suffix = ' FOR UPDATE OF queue' if lock_rows else ''
    rows = conn.execute(
        f'''SELECT queue.id
              FROM target_queue queue
             WHERE queue.id IN ({placeholders})
               AND queue.source = 'dockerhub' AND queue.platform = 'docker'
               AND queue.status IN ('pending','deferred')
               AND queue.target_scan_id IS NULL
               AND queue.target NOT LIKE '%@%' AND queue.normalized_target NOT LIKE '%@%'
               AND queue.lease_owner IS NULL AND queue.lease_token IS NULL
               AND queue.claim_batch IS NULL AND queue.leased_at IS NULL
               AND queue.lease_expires_at IS NULL
               AND queue.current_result_reservation_id IS NULL
               AND queue.claim_event_id IS NULL AND queue.resolver_token IS NULL
               AND COALESCE(queue.resolver_state, '') <> 'resolving'
               AND NOT EXISTS (SELECT 1 FROM target_scans scan WHERE scan.queue_id = queue.id)
                AND NOT EXISTS (
                   SELECT 1 FROM result_reservations reservation
                    WHERE reservation.queue_id = queue.id
                      AND reservation.state IN ('scanning','ready','ingesting','db_committed')
               )
               AND NOT EXISTS (
                   SELECT 1 FROM result_reservations reservation
                   JOIN pipeline_quarantine quarantine
                     ON quarantine.reservation_id = reservation.id
                    WHERE reservation.queue_id = queue.id
               )
               AND NOT EXISTS (
                   SELECT 1 FROM docker_image_manifests image_manifest
                    WHERE image_manifest.target_queue_id = queue.id
               )
               AND NOT EXISTS (
                   SELECT 1 FROM docker_image_blob_coverage coverage
                   JOIN docker_content_blobs blob
                     ON blob.digest = coverage.blob_digest
                    AND blob.coverage_policy_sha256 = coverage.coverage_policy_sha256
                    WHERE coverage.queue_id = queue.id
                      AND blob.state IN ('leased','submitted')
               )
             ORDER BY queue.id{lock_suffix}''',
        tuple(queue_ids),
    ).fetchall()
    if [int(row['id']) for row in rows] != queue_ids:
        raise RuntimeError('Docker depth cohort selection drifted after review')
    _require_released_policy_history(conn, queue_ids)


def apply_docker_depth_cohort_manifest(
    db, experiment, provenance_policy_sha256, manifest, manifest_sha256,
):
    """Atomically persist only the exact currently eligible reviewed cohort."""
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    manifest, expected_sha256 = validate_docker_depth_cohort_manifest(
        manifest, experiment, provenance_policy_sha256,
    )
    if str(manifest_sha256 or '') != expected_sha256:
        raise ValueError('Docker depth cohort manifest hash conflicts')
    plan = manifest['plan']
    plan_sha256 = manifest['plan_sha256']
    conn = _require_postgres_experiment_db(db, 'Docker depth cohort application')
    now = datetime.now(timezone.utc).isoformat(timespec='seconds')
    try:
        _require_complete_docker_depth_collection_pass(conn, authority)
        conn.execute(
            '''INSERT INTO docker_depth_experiments(
                   experiment_key, source, state, collection_generation,
                   config_sha256, ordered_queries_sha256, selector_version,
                   selector_sha256, provenance_policy_sha256, query_count,
                   repositories_per_query, images_per_repository, target_limit,
                   created_at, updated_at
               ) VALUES (?, ?, 'collecting', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
               ON CONFLICT(experiment_key) DO NOTHING''',
            (
                authority['experiment_key'], authority['source'],
                authority['collection_generation'], authority['config_sha256'],
                authority['ordered_queries_sha256'], authority['selector_version'],
                authority['selector_sha256'], authority['provenance_policy_sha256'],
                authority['query_count'], authority['repositories_per_query'],
                authority['images_per_repository'], authority['target_limit'], now, now,
            ),
        )
        row = conn.execute(
            '''SELECT * FROM docker_depth_experiments
               WHERE experiment_key = ? FOR UPDATE''',
            (authority['experiment_key'],),
        ).fetchone()
        if not row or not _experiment_identity_matches(row, authority):
            raise RuntimeError('Docker depth experiment authority is absent or drifted')
        if _experiment_fence_active(row):
            raise RuntimeError('Docker depth experiment has an active authority fence')
        if row['plan_sha256'] is not None:
            stored = _stored_cohort_plan(conn, row, authority)
            stored_sha256 = canonical_docker_depth_plan_hash(stored)
            if (
                stored != plan
                or stored_sha256 != plan_sha256
                or str(row['plan_sha256']) != plan_sha256
                or str(row['state']) not in ('planned', 'holding')
            ):
                raise RuntimeError('Docker depth reviewed cohort authority conflicts')
            _require_planned_cohort_current(conn, stored, True)
            candidates_by_query, _coverage = _fresh_cohort_candidates(
                conn, authority, include_experiment_id=int(row['id']),
            )
            current = build_docker_depth_cohort_manifest(
                experiment, provenance_policy_sha256, candidates_by_query,
            )
            if current != manifest or _canonical_sha256(current) != expected_sha256:
                raise RuntimeError('Docker depth cohort provenance drifted after review')
            conn.commit()
            return {
                'experiment_id': int(row['id']),
                'state': str(row['state']),
                'planning_allowed': True,
                'planned': False,
                'plan': stored,
                'plan_sha256': stored_sha256,
            }
        if str(row['state']) != 'collecting':
            raise RuntimeError('Docker depth experiment is not in collecting state')
        if _cohort_partial_count(conn, row['id']):
            raise RuntimeError('Docker depth collecting experiment has a partial cohort')
        _lock_cohort_manifest_rows(conn, manifest)
        _require_planned_cohort_current(conn, manifest['plan'], True)
        candidates_by_query, _coverage = _fresh_cohort_candidates(conn, authority)
        current = build_docker_depth_cohort_manifest(
            experiment, provenance_policy_sha256, candidates_by_query,
        )
        current, current_sha256 = validate_docker_depth_cohort_manifest(
            current, experiment, provenance_policy_sha256,
        )
        if current != manifest or current_sha256 != expected_sha256:
            raise RuntimeError('Docker depth cohort selection drifted after review')
        experiment_id = int(row['id'])
        for query_plan in plan['queries']:
            conn.execute(
                '''INSERT INTO docker_depth_experiment_queries(
                       experiment_id, source, query_ordinal, query, query_sha256,
                       required_repository_count, selected_repository_count, created_at
                    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?)''',
                (
                    experiment_id, authority['source'], query_plan['query_ordinal'],
                    query_plan['query'], query_plan['query_sha256'],
                     authority['repositories_per_query'],
                    query_plan['selected_repository_count'], now,
                ),
            )
            for repository in query_plan['repositories']:
                conn.execute(
                    '''INSERT INTO docker_depth_experiment_repositories(
                           experiment_id, query_ordinal, source, query,
                           repository_queue_id, eligibility_page_id, repository_rank,
                           planned_is_deep_probe, is_deep_probe, work_state,
                           created_at, updated_at
                       ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 'pending', ?, ?)''',
                    (
                        experiment_id, query_plan['query_ordinal'], authority['source'],
                        query_plan['query'], repository['repository_queue_id'],
                        repository['eligibility_page_id'], repository['repository_rank'],
                        int(repository['is_deep_probe']), int(repository['is_deep_probe']),
                        now, now,
                    ),
                )
        cursor = conn.execute(
            '''UPDATE docker_depth_experiments
               SET state = 'planned', plan_sha256 = ?, planned_at = ?, updated_at = ?
               WHERE id = ? AND state = 'collecting' AND plan_sha256 IS NULL
                 AND target_count = 0 AND selection_count = 0''',
            (plan_sha256, now, now, experiment_id),
        )
        if int(cursor.rowcount or 0) != 1:
            raise RuntimeError('Docker depth cohort plan lost its authority fence')
        conn.commit()
        return {
            'experiment_id': experiment_id,
            'state': 'planned',
            'planning_allowed': True,
            'planned': True,
            'plan': plan,
            'plan_sha256': plan_sha256,
        }
    except Exception:
        conn.rollback()
        raise


def plan_docker_depth_experiment(
    db, experiment, provenance_policy_sha256, *, manifest=None,
    manifest_sha256=None,
):
    """Compatibility name that cannot bypass reviewed cohort approval."""
    if manifest is None or manifest_sha256 is None:
        raise RuntimeError('Docker depth planning requires a reviewed cohort manifest')
    return apply_docker_depth_cohort_manifest(
        db, experiment, provenance_policy_sha256, manifest, manifest_sha256,
    )


def _experiment_row(conn, authority, lock_rows):
    lock_suffix = ' FOR UPDATE' if lock_rows else ''
    row = conn.execute(
        f'''SELECT * FROM docker_depth_experiments
            WHERE experiment_key = ?{lock_suffix}''',
        (authority['experiment_key'],),
    ).fetchone()
    if not row or not _experiment_identity_matches(row, authority):
        raise RuntimeError('Docker depth experiment authority is absent or drifted')
    return row


def _locked_experiment_row(conn, authority):
    return _experiment_row(conn, authority, True)


def _persisted_experiment_drift_reason(db, row, authority, now):
    checker = getattr(db, '_docker_depth_persisted_drift_reason_locked', None)
    if not callable(checker):
        raise RuntimeError('Docker depth persisted authority validator is unavailable')
    return checker(row, authority, now)


def _require_persisted_experiment_authority(db, conn, row, authority, now):
    holder = getattr(db, '_hold_docker_depth_experiment_locked', None)
    if not callable(holder):
        raise RuntimeError('Docker depth persisted authority validator is unavailable')
    reason = _persisted_experiment_drift_reason(db, row, authority, now)
    if reason:
        holder(row, reason, now)
        conn.commit()
        raise RuntimeError(f'Docker depth persisted authority drifted: {reason}')


def _noncohort_hold_snapshot(conn, experiment_id, source, maximum, lock_rows):
    lock_suffix = ' FOR UPDATE OF queue' if lock_rows else ''
    rows = conn.execute(
        f'''SELECT queue.id, queue.source, queue.platform, queue.query,
                   queue.status, queue.updated_at, queue.target_scan_id,
                   queue.resolver_state, queue.lease_owner, queue.lease_token,
                   queue.claim_batch, queue.leased_at, queue.lease_expires_at,
                   queue.current_result_reservation_id, queue.claim_event_id,
                   queue.resolver_token,
                   EXISTS (
                       SELECT 1 FROM result_reservations reservation
                       WHERE reservation.queue_id = queue.id
                         AND reservation.state IN ('scanning','ready','ingesting','db_committed')
                   ) AS active_reservation,
                   EXISTS (
                       SELECT 1 FROM docker_image_blob_coverage coverage
                       JOIN docker_content_blobs blob
                         ON blob.digest = coverage.blob_digest
                        AND blob.coverage_policy_sha256 = coverage.coverage_policy_sha256
                       WHERE coverage.queue_id = queue.id
                         AND blob.state IN ('leased','submitted')
                   ) AS active_docker_blob,
                   EXISTS (
                       SELECT 1 FROM result_reservations reservation
                       JOIN pipeline_quarantine quarantine
                         ON quarantine.reservation_id = reservation.id
                       WHERE reservation.queue_id = queue.id
                   ) AS quarantined_reservation,
                   EXISTS (
                       SELECT 1 FROM target_scans scan WHERE scan.queue_id = queue.id
                   ) AS prior_scan,
                   EXISTS (
                       SELECT 1 FROM target_queue_policy_events event
                       WHERE event.queue_id = queue.id
                   ) AS prior_policy_event
            FROM target_queue queue
            WHERE queue.source = ? AND queue.platform = 'docker'
              AND queue.target NOT LIKE '%@%' AND queue.normalized_target NOT LIKE '%@%'
              AND queue.status NOT IN ('done','failed')
              AND NOT EXISTS (
                  SELECT 1 FROM docker_depth_experiment_repositories member
                  WHERE member.experiment_id = ?
                    AND member.repository_queue_id = queue.id
              )
            ORDER BY queue.id LIMIT ?{lock_suffix}''',
        (source, experiment_id, maximum + 1),
    ).fetchall()
    if len(rows) > maximum:
        raise RuntimeError(
            f'Docker depth hold selection exceeds its reviewed {maximum}-row bound'
        )
    entries = []
    conflicts = []
    fence_fields = (
        'lease_owner', 'lease_token', 'claim_batch', 'leased_at', 'lease_expires_at',
        'current_result_reservation_id', 'claim_event_id', 'resolver_token',
    )
    for row in rows:
        status = str(row['status'] or '')
        query = str(row['query'] or '')
        reason = None
        if status == 'cold':
            reason = 'independently_cold'
        elif status in ('done', 'failed'):
            reason = 'terminal_status'
        elif status == 'quarantined' or bool(row['quarantined_reservation']):
            reason = 'quarantined'
        elif row['target_scan_id'] is not None or bool(row['prior_scan']):
            reason = 'previously_scanned'
        elif status not in ('pending', 'deferred'):
            reason = 'ineligible_status'
        elif any(row[field] is not None for field in fence_fields):
            reason = 'active_claim_fence'
        elif str(row['resolver_state'] or '') == 'resolving':
            reason = 'active_resolver_fence'
        elif bool(row['active_reservation']) or bool(row['active_docker_blob']):
            reason = 'active_content_fence'
        elif bool(row['prior_policy_event']):
            reason = 'unrelated_policy_event'
        elif not query:
            reason = 'missing_query_identity'
        if reason is None:
            entries.append({
                'queue_id': int(row['id']),
                'source': str(row['source']),
                'platform': str(row['platform']),
                'query': query,
                'prior_status': status,
                'prior_updated_at': str(row['updated_at']),
            })
        else:
            conflicts.append({
                'queue_id': int(row['id']),
                'source': str(row['source']),
                'platform': str(row['platform']),
                'query': query,
                'status': status,
                'prior_updated_at': str(row['updated_at']),
                'reason': reason,
            })
    return entries, conflicts


def _hold_manifest_document(authority, experiment_row, entries, conflicts):
    return {
        'schema': 1,
        'type': DOCKER_DEPTH_HOLD_MANIFEST_TYPE,
        'experiment_id': int(experiment_row['id']),
        'experiment_key': authority['experiment_key'],
        'source': authority['source'],
        'config_sha256': authority['config_sha256'],
        'ordered_queries_sha256': authority['ordered_queries_sha256'],
        'selector_sha256': authority['selector_sha256'],
        'provenance_policy_sha256': authority['provenance_policy_sha256'],
        'plan_sha256': str(experiment_row['plan_sha256']),
        'reason_code': DOCKER_DEPTH_HOLD_REASON,
        'entry_count': len(entries),
        'conflict_count': len(conflicts),
        'selection_sha256': _canonical_sha256(entries),
        'conflicts_sha256': _canonical_sha256(conflicts),
        'entries': entries,
        'conflicts': conflicts,
    }


def _normalize_hold_entries(entries, maximum):
    if not isinstance(entries, list) or len(entries) > maximum:
        raise ValueError('Docker depth hold manifest entries exceed their bound')
    required = {
        'queue_id', 'source', 'platform', 'query', 'prior_status', 'prior_updated_at',
    }
    normalized = []
    seen = set()
    for raw in entries:
        if not isinstance(raw, dict) or set(raw) != required:
            raise ValueError('Docker depth hold manifest entry shape is invalid')
        queue_id = _strict_positive_int(raw['queue_id'], 'queue_id')
        if queue_id in seen:
            raise ValueError('Docker depth hold manifest contains a duplicate queue row')
        seen.add(queue_id)
        item = {
            'queue_id': queue_id,
            'source': str(raw['source'] or ''),
            'platform': str(raw['platform'] or ''),
            'query': str(raw['query'] or ''),
            'prior_status': str(raw['prior_status'] or ''),
            'prior_updated_at': str(raw['prior_updated_at'] or ''),
        }
        if (
            item['source'] != 'dockerhub'
            or item['platform'] != 'docker'
            or not item['query']
            or item['prior_status'] not in ('pending', 'deferred')
            or not item['prior_updated_at']
        ):
            raise ValueError('Docker depth hold manifest entry identity is invalid')
        normalized.append(item)
    normalized.sort(key=lambda item: item['queue_id'])
    return normalized


def _normalize_hold_conflicts(conflicts, maximum):
    if not isinstance(conflicts, list) or len(conflicts) > maximum:
        raise ValueError('Docker depth hold manifest conflicts exceed their bound')
    required = {
        'queue_id', 'source', 'platform', 'query', 'status', 'prior_updated_at', 'reason',
    }
    allowed_reasons = {
        'independently_cold', 'terminal_status', 'quarantined', 'previously_scanned',
        'ineligible_status', 'active_claim_fence', 'active_resolver_fence',
        'active_content_fence', 'unrelated_policy_event', 'missing_query_identity',
    }
    normalized = []
    seen = set()
    for raw in conflicts:
        if not isinstance(raw, dict) or set(raw) != required:
            raise ValueError('Docker depth hold conflict shape is invalid')
        queue_id = _strict_positive_int(raw['queue_id'], 'queue_id')
        if queue_id in seen:
            raise ValueError('Docker depth hold conflicts contain a duplicate queue row')
        seen.add(queue_id)
        item = {
            'queue_id': queue_id,
            'source': str(raw['source'] or ''),
            'platform': str(raw['platform'] or ''),
            'query': str(raw['query'] or ''),
            'status': str(raw['status'] or ''),
            'prior_updated_at': str(raw['prior_updated_at'] or ''),
            'reason': str(raw['reason'] or ''),
        }
        if (
            item['source'] != 'dockerhub'
            or item['platform'] != 'docker'
            or not item['prior_updated_at']
            or item['reason'] not in allowed_reasons
        ):
            raise ValueError('Docker depth hold conflict identity is invalid')
        normalized.append(item)
    normalized.sort(key=lambda item: item['queue_id'])
    return normalized


def validate_docker_depth_hold_manifest(
    manifest, experiment=None, provenance_policy_sha256=None,
    max_rows=DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
):
    maximum = min(
        DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
        _strict_positive_int(max_rows, 'max_rows'),
    )
    expected_keys = {
        'schema', 'type', 'experiment_id', 'experiment_key', 'source',
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'reason_code', 'entry_count',
        'conflict_count', 'selection_sha256', 'conflicts_sha256', 'entries', 'conflicts',
    }
    if (
        not isinstance(manifest, dict)
        or set(manifest) != expected_keys
        or type(manifest.get('schema')) is not int
        or manifest.get('schema') != 1
        or manifest.get('type') != DOCKER_DEPTH_HOLD_MANIFEST_TYPE
    ):
        raise ValueError('Docker depth hold manifest shape is invalid')
    entries = _normalize_hold_entries(manifest['entries'], maximum)
    conflicts = _normalize_hold_conflicts(manifest['conflicts'], maximum)
    if entries != manifest['entries'] or conflicts != manifest['conflicts']:
        raise ValueError('Docker depth hold manifest rows are not canonical')
    if len(entries) + len(conflicts) > maximum:
        raise ValueError('Docker depth hold manifest selection exceeds its bound')
    if set(item['queue_id'] for item in entries).intersection(
        item['queue_id'] for item in conflicts
    ):
        raise ValueError('Docker depth hold manifest entry and conflict sets overlap')
    hashes = (
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'selection_sha256',
        'conflicts_sha256',
    )
    if any(not _valid_sha256(manifest.get(name)) for name in hashes):
        raise ValueError('Docker depth hold manifest contains an invalid hash')
    entry_count = _strict_nonnegative_int(manifest['entry_count'], 'entry_count')
    conflict_count = _strict_nonnegative_int(
        manifest['conflict_count'], 'conflict_count',
    )
    _strict_identifier(manifest['experiment_key'], 'experiment_key')
    if (
        _strict_positive_int(manifest['experiment_id'], 'experiment_id') <= 0
        or manifest['source'] != 'dockerhub'
        or manifest['reason_code'] != DOCKER_DEPTH_HOLD_REASON
        or entry_count != len(entries)
        or conflict_count != len(conflicts)
        or manifest['selection_sha256'] != _canonical_sha256(entries)
        or manifest['conflicts_sha256'] != _canonical_sha256(conflicts)
    ):
        raise ValueError('Docker depth hold manifest evidence conflicts')
    if experiment is not None:
        authority = _docker_depth_authority(
            experiment,
            provenance_policy_sha256 or manifest['provenance_policy_sha256'],
        )
        for manifest_name, authority_name in (
            ('experiment_key', 'experiment_key'),
            ('source', 'source'),
            ('config_sha256', 'config_sha256'),
            ('ordered_queries_sha256', 'ordered_queries_sha256'),
            ('selector_sha256', 'selector_sha256'),
            ('provenance_policy_sha256', 'provenance_policy_sha256'),
        ):
            if manifest[manifest_name] != authority[authority_name]:
                raise ValueError('Docker depth hold manifest authority drifted')
    normalized = copy.deepcopy(manifest)
    return normalized, _canonical_sha256(normalized)


def generate_docker_depth_hold_manifest(
    db, experiment, provenance_policy_sha256,
    max_rows=DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    conn = _require_postgres_experiment_db(db, 'Docker depth hold planning')
    maximum = min(
        DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
        _strict_positive_int(max_rows, 'max_rows'),
    )
    try:
        row = _experiment_row(conn, authority, False)
        if str(row['state']) != 'planned' or not _valid_sha256(row['plan_sha256']):
            raise RuntimeError('Docker depth hold planning requires an immutable planned cohort')
        if _experiment_fence_active(row):
            raise RuntimeError('Docker depth experiment has an active authority fence')
        plan = _stored_cohort_plan(conn, row, authority)
        if canonical_docker_depth_plan_hash(plan) != str(row['plan_sha256']):
            raise RuntimeError('Docker depth hold planning found plan hash drift')
        _require_planned_cohort_current(conn, plan, False)
        entries, conflicts = _noncohort_hold_snapshot(
            conn, int(row['id']), authority['source'], maximum, False,
        )
        manifest = _hold_manifest_document(authority, row, entries, conflicts)
        manifest, manifest_sha256 = validate_docker_depth_hold_manifest(
            manifest, experiment, provenance_policy_sha256, maximum,
        )
        conn.commit()
        return manifest, manifest_sha256
    except Exception:
        conn.rollback()
        raise


def apply_docker_depth_hold_manifest(
    db, experiment, provenance_policy_sha256, manifest, manifest_sha256,
    max_rows=DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    manifest, expected_sha256 = validate_docker_depth_hold_manifest(
        manifest, experiment, provenance_policy_sha256, max_rows,
    )
    if str(manifest_sha256 or '') != expected_sha256:
        raise ValueError('Docker depth hold manifest hash conflicts')
    conn = _require_postgres_experiment_db(db, 'Docker depth hold application')
    maximum = min(
        DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
        _strict_positive_int(max_rows, 'max_rows'),
    )
    now = datetime.now(timezone.utc).isoformat(timespec='seconds')
    try:
        row = _locked_experiment_row(conn, authority)
        if _experiment_fence_active(row):
            raise RuntimeError('Docker depth experiment has an active authority fence')
        if int(row['id']) != manifest['experiment_id']:
            raise RuntimeError('Docker depth hold manifest experiment identity drifted')
        if str(row['plan_sha256'] or '') != manifest['plan_sha256']:
            raise RuntimeError('Docker depth hold manifest plan identity drifted')
        plan = _stored_cohort_plan(conn, row, authority)
        if canonical_docker_depth_plan_hash(plan) != manifest['plan_sha256']:
            raise RuntimeError('Docker depth hold manifest plan identity drifted')
        _require_planned_cohort_current(conn, plan, True)
        stored_manifest_sha256 = str(row['hold_manifest_sha256'] or '')
        if stored_manifest_sha256:
            _require_persisted_experiment_authority(
                db, conn, row, authority, now,
            )
            if (
                stored_manifest_sha256 != expected_sha256
                or str(row['state']) != 'holding'
            ):
                raise RuntimeError('Docker depth reviewed hold authority conflicts')
            reviewed_rows = conn.execute(
                '''SELECT queue_id, reason_code, manifest_sha256
                     FROM target_queue_policy_events
                    WHERE experiment_id = ? AND action = 'cold'
                    ORDER BY queue_id, id''',
                (row['id'],),
            ).fetchall()
            if (
                [int(item['queue_id']) for item in reviewed_rows]
                != [item['queue_id'] for item in manifest['entries']]
                or any(
                    str(item['reason_code']) != DOCKER_DEPTH_HOLD_REASON
                    or str(item['manifest_sha256']) != expected_sha256
                    for item in reviewed_rows
                )
            ):
                raise RuntimeError('Docker depth reviewed hold set changed')
        else:
            if str(row['state']) != 'planned':
                raise RuntimeError('Docker depth experiment is not ready for reviewed holds')
            entries, conflicts = _noncohort_hold_snapshot(
                conn, int(row['id']), authority['source'], maximum, True,
            )
            current = _hold_manifest_document(authority, row, entries, conflicts)
            if current != manifest:
                raise RuntimeError('Docker depth hold selection drifted after review')
        entries = db._normalize_target_queue_policy_entries(
            manifest['entries'], 'cold', maximum,
        ) if manifest['entries'] else []
        result = db._cold_target_queue_rows_locked(
            entries,
            reason_code=DOCKER_DEPTH_HOLD_REASON,
            config_sha256=authority['config_sha256'],
            policy_sha256=authority['provenance_policy_sha256'],
            manifest_sha256=expected_sha256,
            experiment_id=int(row['id']),
            now=now,
        )
        if not stored_manifest_sha256:
            cursor = conn.execute(
                '''UPDATE docker_depth_experiments
                   SET state = 'holding', hold_manifest_sha256 = ?,
                       activated_at = COALESCE(activated_at, ?), updated_at = ?
                   WHERE id = ? AND state = 'planned'
                     AND plan_sha256 = ? AND hold_manifest_sha256 IS NULL''',
                (expected_sha256, now, now, row['id'], manifest['plan_sha256']),
            )
            if int(cursor.rowcount or 0) != 1:
                raise RuntimeError('Docker depth hold activation lost its authority fence')
        conn.commit()
        return {
            **result,
            'experiment_id': int(row['id']),
            'state': 'holding' if not stored_manifest_sha256 else str(row['state']),
            'conflicts': manifest['conflict_count'],
        }
    except Exception:
        conn.rollback()
        raise


def _experiment_reactivation_entries(conn, experiment_id, maximum, lock_rows):
    lock_suffix = ' FOR UPDATE OF queue, cold_event' if lock_rows else ''
    rows = conn.execute(
        f'''SELECT queue.*, cold_event.id AS cold_event_id,
                   cold_event.prior_status AS restore_status,
                   reverse_event.id AS reverse_event_id
            FROM target_queue_policy_events cold_event
            JOIN target_queue queue ON queue.id = cold_event.queue_id
            LEFT JOIN target_queue_policy_events reverse_event
              ON reverse_event.reverses_event_id = cold_event.id
            WHERE cold_event.experiment_id = ? AND cold_event.action = 'cold'
              AND reverse_event.id IS NULL
            ORDER BY queue.id, cold_event.id LIMIT ?{lock_suffix}''',
        (experiment_id, maximum + 1),
    ).fetchall()
    if len(rows) > maximum:
        raise RuntimeError(
            f'Docker depth reactivation selection exceeds its reviewed {maximum}-row bound'
        )
    entries = []
    seen = set()
    for row in rows:
        queue_id = int(row['id'])
        if queue_id in seen or row['reverse_event_id'] is not None or row['status'] != 'cold':
            raise RuntimeError('Docker depth reactivation evidence conflicts')
        seen.add(queue_id)
        entries.append({
            'queue_id': queue_id,
            'source': str(row['source']),
            'platform': str(row['platform']),
            'query': str(row['query']),
            'cold_event_id': int(row['cold_event_id']),
            'restore_status': str(row['restore_status']),
            'prior_updated_at': str(row['updated_at']),
        })
    return entries


def _reactivation_manifest_document(authority, experiment_row, entries):
    return {
        'schema': 1,
        'type': DOCKER_DEPTH_REACTIVATION_MANIFEST_TYPE,
        'experiment_id': int(experiment_row['id']),
        'experiment_key': authority['experiment_key'],
        'source': authority['source'],
        'config_sha256': authority['config_sha256'],
        'ordered_queries_sha256': authority['ordered_queries_sha256'],
        'selector_sha256': authority['selector_sha256'],
        'provenance_policy_sha256': authority['provenance_policy_sha256'],
        'plan_sha256': str(experiment_row['plan_sha256']),
        'hold_manifest_sha256': str(experiment_row['hold_manifest_sha256']),
        'reason_code': DOCKER_DEPTH_RELEASE_REASON,
        'entry_count': len(entries),
        'selection_sha256': _canonical_sha256(entries),
        'entries': entries,
    }


def _normalize_reactivation_entries(entries, maximum):
    if not isinstance(entries, list) or len(entries) > maximum:
        raise ValueError('Docker depth reactivation entries exceed their bound')
    required = {
        'queue_id', 'source', 'platform', 'query', 'cold_event_id',
        'restore_status', 'prior_updated_at',
    }
    normalized = []
    queue_ids = set()
    event_ids = set()
    for raw in entries:
        if not isinstance(raw, dict) or set(raw) != required:
            raise ValueError('Docker depth reactivation entry shape is invalid')
        queue_id = _strict_positive_int(raw['queue_id'], 'queue_id')
        event_id = _strict_positive_int(raw['cold_event_id'], 'cold_event_id')
        if queue_id in queue_ids or event_id in event_ids:
            raise ValueError('Docker depth reactivation identity is duplicated')
        queue_ids.add(queue_id)
        event_ids.add(event_id)
        item = {
            'queue_id': queue_id,
            'source': str(raw['source'] or ''),
            'platform': str(raw['platform'] or ''),
            'query': str(raw['query'] or ''),
            'cold_event_id': event_id,
            'restore_status': str(raw['restore_status'] or ''),
            'prior_updated_at': str(raw['prior_updated_at'] or ''),
        }
        if (
            item['source'] != 'dockerhub'
            or item['platform'] != 'docker'
            or not item['query']
            or item['restore_status'] not in ('pending', 'deferred')
            or not item['prior_updated_at']
        ):
            raise ValueError('Docker depth reactivation entry identity is invalid')
        normalized.append(item)
    normalized.sort(key=lambda item: item['queue_id'])
    return normalized


def validate_docker_depth_reactivation_manifest(
    manifest, experiment=None, provenance_policy_sha256=None,
    max_rows=DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
):
    maximum = min(
        DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
        _strict_positive_int(max_rows, 'max_rows'),
    )
    expected_keys = {
        'schema', 'type', 'experiment_id', 'experiment_key', 'source',
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'hold_manifest_sha256',
        'reason_code', 'entry_count', 'selection_sha256', 'entries',
    }
    if (
        not isinstance(manifest, dict)
        or set(manifest) != expected_keys
        or type(manifest.get('schema')) is not int
        or manifest.get('schema') != 1
        or manifest.get('type') != DOCKER_DEPTH_REACTIVATION_MANIFEST_TYPE
    ):
        raise ValueError('Docker depth reactivation manifest shape is invalid')
    entries = _normalize_reactivation_entries(manifest['entries'], maximum)
    if entries != manifest['entries']:
        raise ValueError('Docker depth reactivation entries are not canonical')
    for name in (
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'hold_manifest_sha256',
        'selection_sha256',
    ):
        if not _valid_sha256(manifest.get(name)):
            raise ValueError('Docker depth reactivation manifest contains an invalid hash')
    entry_count = _strict_nonnegative_int(manifest['entry_count'], 'entry_count')
    _strict_identifier(manifest['experiment_key'], 'experiment_key')
    if (
        _strict_positive_int(manifest['experiment_id'], 'experiment_id') <= 0
        or manifest['source'] != 'dockerhub'
        or manifest['reason_code'] != DOCKER_DEPTH_RELEASE_REASON
        or entry_count != len(entries)
        or manifest['selection_sha256'] != _canonical_sha256(entries)
    ):
        raise ValueError('Docker depth reactivation evidence conflicts')
    if experiment is not None:
        authority = _docker_depth_authority(
            experiment,
            provenance_policy_sha256 or manifest['provenance_policy_sha256'],
        )
        for manifest_name, authority_name in (
            ('experiment_key', 'experiment_key'), ('source', 'source'),
            ('config_sha256', 'config_sha256'),
            ('ordered_queries_sha256', 'ordered_queries_sha256'),
            ('selector_sha256', 'selector_sha256'),
            ('provenance_policy_sha256', 'provenance_policy_sha256'),
        ):
            if manifest[manifest_name] != authority[authority_name]:
                raise ValueError('Docker depth reactivation authority drifted')
    normalized = copy.deepcopy(manifest)
    return normalized, _canonical_sha256(normalized)


def generate_docker_depth_reactivation_manifest(
    db, experiment, provenance_policy_sha256,
    max_rows=DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    conn = _require_postgres_experiment_db(db, 'Docker depth reactivation planning')
    maximum = min(
        DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
        _strict_positive_int(max_rows, 'max_rows'),
    )
    try:
        row = _experiment_row(conn, authority, False)
        if (
            str(row['state']) != 'completed'
            or not _valid_sha256(row['plan_sha256'])
            or not _valid_sha256(row['hold_manifest_sha256'])
        ):
            raise RuntimeError('Docker depth reactivation requires a completed experiment')
        now = datetime.now(timezone.utc).isoformat(timespec='seconds')
        reason = _persisted_experiment_drift_reason(db, row, authority, now)
        if reason:
            raise RuntimeError(f'Docker depth persisted authority drifted: {reason}')
        entries = _experiment_reactivation_entries(
            conn, int(row['id']), maximum, False,
        )
        for entry in entries:
            queue = conn.execute(
                'SELECT * FROM target_queue WHERE id = ?',
                (entry['queue_id'],),
            ).fetchone()
            db._require_target_queue_policy_unfenced(queue, lock_rows=False)
        manifest = _reactivation_manifest_document(authority, row, entries)
        manifest, manifest_sha256 = validate_docker_depth_reactivation_manifest(
            manifest, experiment, provenance_policy_sha256, maximum,
        )
        conn.commit()
        return manifest, manifest_sha256
    except Exception:
        conn.rollback()
        raise


def _require_released_reactivation_replay(
    conn, experiment_id, manifest, manifest_sha256,
):
    rows = conn.execute(
        '''SELECT cold_event.id AS cold_event_id, cold_event.queue_id,
                  cold_event.reason_code AS cold_reason_code,
                  cold_event.config_sha256 AS cold_config_sha256,
                  cold_event.policy_sha256 AS cold_policy_sha256,
                  cold_event.manifest_sha256 AS cold_manifest_sha256,
                  reverse_event.id AS reverse_event_id,
                  reverse_event.action AS reverse_action,
                  reverse_event.experiment_id AS reverse_experiment_id,
                  reverse_event.reason_code AS reverse_reason_code,
                  reverse_event.config_sha256 AS reverse_config_sha256,
                  reverse_event.policy_sha256 AS reverse_policy_sha256,
                  reverse_event.manifest_sha256 AS reverse_manifest_sha256,
                  queue.status AS queue_status
             FROM target_queue_policy_events cold_event
             JOIN target_queue queue ON queue.id = cold_event.queue_id
             LEFT JOIN target_queue_policy_events reverse_event
               ON reverse_event.reverses_event_id = cold_event.id
            WHERE cold_event.experiment_id = ? AND cold_event.action = 'cold'
            ORDER BY cold_event.queue_id, cold_event.id''',
        (experiment_id,),
    ).fetchall()
    expected = [
        (entry['queue_id'], entry['cold_event_id']) for entry in manifest['entries']
    ]
    actual = [(int(row['queue_id']), int(row['cold_event_id'])) for row in rows]
    if actual != expected or any(
        str(row['cold_reason_code']) not in (
            DOCKER_DEPTH_HOLD_REASON, DOCKER_DEPTH_DYNAMIC_HOLD_REASON,
        )
        or str(row['cold_config_sha256']) != manifest['config_sha256']
        or str(row['cold_policy_sha256']) != manifest['provenance_policy_sha256']
        or str(row['cold_manifest_sha256']) != manifest['hold_manifest_sha256']
        or row['reverse_event_id'] is None
        or str(row['reverse_action']) != 'reactivate'
        or row['reverse_experiment_id'] is None
        or int(row['reverse_experiment_id']) != experiment_id
        or str(row['reverse_reason_code']) != DOCKER_DEPTH_RELEASE_REASON
        or str(row['reverse_config_sha256']) != manifest['config_sha256']
        or str(row['reverse_policy_sha256']) != manifest['provenance_policy_sha256']
        or str(row['reverse_manifest_sha256']) != manifest_sha256
        or str(row['queue_status']) != manifest['entries'][index]['restore_status']
        for index, row in enumerate(rows)
    ):
        raise RuntimeError('Docker depth released hold set changed')


def apply_docker_depth_reactivation_manifest(
    db, experiment, provenance_policy_sha256, manifest, manifest_sha256,
    max_rows=DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    manifest, expected_sha256 = validate_docker_depth_reactivation_manifest(
        manifest, experiment, provenance_policy_sha256, max_rows,
    )
    if str(manifest_sha256 or '') != expected_sha256:
        raise ValueError('Docker depth reactivation manifest hash conflicts')
    conn = _require_postgres_experiment_db(db, 'Docker depth reactivation')
    maximum = min(
        DOCKER_DEPTH_REVIEW_MANIFEST_MAX_ROWS,
        _strict_positive_int(max_rows, 'max_rows'),
    )
    now = datetime.now(timezone.utc).isoformat(timespec='seconds')
    try:
        row = _locked_experiment_row(conn, authority)
        if (
            int(row['id']) != manifest['experiment_id']
            or str(row['plan_sha256'] or '') != manifest['plan_sha256']
            or str(row['hold_manifest_sha256'] or '') != manifest['hold_manifest_sha256']
        ):
            raise RuntimeError('Docker depth reactivation experiment identity drifted')
        plan = _stored_cohort_plan(conn, row, authority)
        if canonical_docker_depth_plan_hash(plan) != manifest['plan_sha256']:
            raise RuntimeError('Docker depth reactivation cohort identity drifted')
        released = str(row['state']) == 'released'
        if released:
            _require_released_reactivation_replay(
                conn, int(row['id']), manifest, expected_sha256,
            )
        else:
            if str(row['state']) != 'completed':
                raise RuntimeError('Docker depth reactivation requires a completed experiment')
            _require_persisted_experiment_authority(
                db, conn, row, authority, now,
            )
            current_entries = _experiment_reactivation_entries(
                conn, int(row['id']), maximum, True,
            )
            current = _reactivation_manifest_document(authority, row, current_entries)
            if current != manifest:
                raise RuntimeError('Docker depth reactivation selection drifted after review')
        entries = db._normalize_target_queue_policy_entries(
            manifest['entries'], 'reactivate', maximum,
        ) if manifest['entries'] else []
        result = db._reactivate_target_queue_rows_locked(
            entries,
            reason_code=DOCKER_DEPTH_RELEASE_REASON,
            config_sha256=authority['config_sha256'],
            policy_sha256=authority['provenance_policy_sha256'],
            manifest_sha256=expected_sha256,
            experiment_id=int(row['id']),
            now=now,
        )
        if not released:
            remaining = conn.execute(
                '''SELECT COUNT(*) AS count
                   FROM target_queue_policy_events cold_event
                   LEFT JOIN target_queue_policy_events reverse_event
                     ON reverse_event.reverses_event_id = cold_event.id
                   WHERE cold_event.experiment_id = ? AND cold_event.action = 'cold'
                     AND reverse_event.id IS NULL''',
                (row['id'],),
            ).fetchone()['count']
            if int(remaining):
                raise RuntimeError('Docker depth reactivation left owned cold events unreversed')
            cursor = conn.execute(
                '''UPDATE docker_depth_experiments
                   SET state = 'released', released_at = COALESCE(released_at, ?),
                       updated_at = ?
                    WHERE id = ? AND state = 'completed'
                     AND hold_manifest_sha256 = ?''',
                (now, now, row['id'], manifest['hold_manifest_sha256']),
            )
            if int(cursor.rowcount or 0) != 1:
                raise RuntimeError('Docker depth release lost its authority fence')
        conn.commit()
        return {
            **result,
            'experiment_id': int(row['id']),
            'state': 'released',
        }
    except Exception:
        conn.rollback()
        raise


def _docker_depth_resolver_refund_text_sha256(value):
    return hashlib.sha256(str(value).encode('utf-8')).hexdigest()


def _docker_depth_resolver_refund_log(path):
    absolute = os.path.abspath(os.fspath(path))
    size = os.path.getsize(absolute)
    if size < 1 or size > DOCKER_DEPTH_RESOLVER_REFUND_LOG_MAX_BYTES:
        raise RuntimeError('Docker depth resolver refund log size is invalid')
    with open(absolute, 'rb') as handle:
        payload = handle.read(DOCKER_DEPTH_RESOLVER_REFUND_LOG_MAX_BYTES + 1)
    if len(payload) != size or len(payload) > DOCKER_DEPTH_RESOLVER_REFUND_LOG_MAX_BYTES:
        raise RuntimeError('Docker depth resolver refund log changed while reading')
    return payload, hashlib.sha256(payload).hexdigest()


def _docker_depth_resolver_refund_entry(row, log_lines):
    target = str(row['normalized_target'] or '')
    if not target:
        raise RuntimeError('Docker depth resolver refund target identity is absent')
    exact_error = (
        f'Unable to fetch Docker Hub tags for {target}: '
        f'{DOCKER_DEPTH_RESOLVER_REFUND_OLD_ERROR}'
    )
    bug_count = sum(exact_error in line for line in log_lines)
    if bug_count != DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS:
        return None
    work_state = str(row['work_state'] or '')
    attempts = int(row['resolver_attempts'])
    last_error = str(row['last_error_code'] or '')
    expected_shape = (
        work_state == 'pending'
        and attempts == DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS
        and last_error == DOCKER_DEPTH_RESOLVER_REFUND_OLD_ERROR
    ) or (
        work_state == 'held'
        and attempts == DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS + 1
        and last_error == 'resolver_attempt_limit'
    )
    if not expected_shape:
        raise RuntimeError('Docker depth bug-tainted resolver state is not refundable')
    entry = {
        'experiment_repository_id': int(row['id']),
        'repository_queue_id': int(row['effective_repository_queue_id']),
        'query_ordinal': int(row['query_ordinal']),
        'repository_rank': int(row['repository_rank']),
        'recovery_kind': DOCKER_DEPTH_RESOLVER_REFUND_KIND,
        'prior_work_state': work_state,
        'next_work_state': 'pending',
        'prior_resolver_attempts': attempts,
        'refund_attempts': DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS,
        'next_resolver_attempts': attempts - DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS,
        'confirmed_bug_event_count': bug_count,
        'prior_error_code_sha256': _docker_depth_resolver_refund_text_sha256(last_error),
        'target_identity_sha256': _docker_depth_resolver_refund_text_sha256(target),
    }
    entry['entry_evidence_sha256'] = _canonical_sha256(entry)
    return entry


def validate_docker_depth_resolver_refund_manifest(
    manifest, experiment=None, provenance_policy_sha256=None,
):
    expected_keys = {
        'schema', 'type', 'version', 'experiment_id', 'experiment_key', 'source',
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'hold_reason_code',
        'recovery_kind', 'refund_attempts', 'evidence_log_name',
        'evidence_log_sha256', 'entry_count', 'held_entry_count',
        'selection_sha256', 'entries',
    }
    if (
        not isinstance(manifest, dict)
        or set(manifest) != expected_keys
        or type(manifest.get('schema')) is not int
        or manifest.get('schema') != 1
        or type(manifest.get('version')) is not int
        or manifest.get('version') != 1
        or manifest.get('type') != DOCKER_DEPTH_RESOLVER_REFUND_MANIFEST_TYPE
    ):
        raise ValueError('Docker depth resolver refund manifest shape is invalid')
    _strict_identifier(manifest.get('experiment_key'), 'experiment_key')
    entries = manifest.get('entries')
    if not isinstance(entries, list) or not entries:
        raise ValueError('Docker depth resolver refund manifest entries are invalid')
    normalized_entries = []
    member_ids = set()
    for raw in entries:
        expected_entry_keys = {
            'experiment_repository_id', 'repository_queue_id', 'query_ordinal',
            'repository_rank', 'recovery_kind', 'prior_work_state',
            'next_work_state', 'prior_resolver_attempts', 'refund_attempts',
            'next_resolver_attempts', 'confirmed_bug_event_count',
            'prior_error_code_sha256', 'target_identity_sha256',
            'entry_evidence_sha256',
        }
        if not isinstance(raw, dict) or set(raw) != expected_entry_keys:
            raise ValueError('Docker depth resolver refund entry shape is invalid')
        item = copy.deepcopy(raw)
        member_id = _strict_positive_int(
            item['experiment_repository_id'], 'experiment_repository_id',
        )
        if member_id in member_ids:
            raise ValueError('Docker depth resolver refund entry is duplicated')
        member_ids.add(member_id)
        _strict_positive_int(item['repository_queue_id'], 'repository_queue_id')
        _strict_nonnegative_int(item['query_ordinal'], 'query_ordinal')
        _strict_positive_int(item['repository_rank'], 'repository_rank')
        prior_attempts = _strict_positive_int(
            item['prior_resolver_attempts'], 'prior_resolver_attempts',
        )
        next_attempts = _strict_nonnegative_int(
            item['next_resolver_attempts'], 'next_resolver_attempts',
        )
        if (
            item['recovery_kind'] != DOCKER_DEPTH_RESOLVER_REFUND_KIND
            or item['prior_work_state'] not in ('pending', 'held')
            or item['next_work_state'] != 'pending'
            or item['refund_attempts'] != DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS
            or item['confirmed_bug_event_count'] != DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS
            or next_attempts != prior_attempts - DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS
            or next_attempts < 0
            or any(not _valid_sha256(item.get(name)) for name in (
                'prior_error_code_sha256', 'target_identity_sha256',
                'entry_evidence_sha256',
            ))
        ):
            raise ValueError('Docker depth resolver refund entry evidence is invalid')
        evidence = dict(item)
        evidence.pop('entry_evidence_sha256')
        if item['entry_evidence_sha256'] != _canonical_sha256(evidence):
            raise ValueError('Docker depth resolver refund entry hash conflicts')
        normalized_entries.append(item)
    normalized_entries.sort(key=lambda item: item['experiment_repository_id'])
    if normalized_entries != entries:
        raise ValueError('Docker depth resolver refund entries are not canonical')
    hashes = (
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'evidence_log_sha256',
        'selection_sha256',
    )
    if any(not _valid_sha256(manifest.get(name)) for name in hashes):
        raise ValueError('Docker depth resolver refund manifest hash is invalid')
    if (
        _strict_positive_int(manifest.get('experiment_id'), 'experiment_id') <= 0
        or manifest.get('source') != 'dockerhub'
        or manifest.get('hold_reason_code') != 'resolver_attempt_limit'
        or manifest.get('recovery_kind') != DOCKER_DEPTH_RESOLVER_REFUND_KIND
        or manifest.get('refund_attempts') != DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS
        or manifest.get('evidence_log_name') != 'dockerhub.log'
        or manifest.get('entry_count') != len(normalized_entries)
        or manifest.get('held_entry_count')
        != sum(item['prior_work_state'] == 'held' for item in normalized_entries)
        or manifest.get('held_entry_count') != 1
        or manifest.get('selection_sha256') != _canonical_sha256(normalized_entries)
    ):
        raise ValueError('Docker depth resolver refund manifest evidence conflicts')
    if experiment is not None:
        authority = _docker_depth_authority(
            experiment,
            provenance_policy_sha256 or manifest['provenance_policy_sha256'],
        )
        for manifest_name, authority_name in (
            ('experiment_key', 'experiment_key'), ('source', 'source'),
            ('config_sha256', 'config_sha256'),
            ('ordered_queries_sha256', 'ordered_queries_sha256'),
            ('selector_sha256', 'selector_sha256'),
            ('provenance_policy_sha256', 'provenance_policy_sha256'),
        ):
            if manifest[manifest_name] != authority[authority_name]:
                raise ValueError('Docker depth resolver refund authority drifted')
    normalized = copy.deepcopy(manifest)
    normalized['entries'] = normalized_entries
    if normalized != manifest:
        raise ValueError('Docker depth resolver refund manifest is not canonical')
    return normalized, _canonical_sha256(normalized)


def generate_docker_depth_resolver_refund_manifest(
    db, experiment, provenance_policy_sha256, evidence_log_path,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    conn = _require_postgres_experiment_db(db, 'Docker depth resolver refund planning')
    log_payload, log_sha256 = _docker_depth_resolver_refund_log(evidence_log_path)
    log_lines = log_payload.decode('utf-8', 'replace').splitlines()
    try:
        row = _experiment_row(conn, authority, False)
        if (
            str(row['state']) != 'held'
            or str(row['hold_reason_code'] or '') != 'resolver_attempt_limit'
            or not _valid_sha256(row['plan_sha256'])
            or _experiment_fence_active(row)
        ):
            raise RuntimeError('Docker depth resolver refund requires an attempt-limit hold')
        members = conn.execute(
            '''SELECT member.*, queue.id AS effective_repository_queue_id,
                      queue.normalized_target
                 FROM docker_depth_experiment_repositories member
                 JOIN target_queue queue
                   ON queue.id = COALESCE(
                       member.replacement_repository_queue_id,
                       member.repository_queue_id
                   )
                WHERE member.experiment_id = ? AND member.resolver_attempts >= ?
                ORDER BY member.id''',
            (row['id'], DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS),
        ).fetchall()
        entries = []
        for member in members:
            entry = _docker_depth_resolver_refund_entry(member, log_lines)
            if entry is not None:
                entries.append(entry)
        if not entries:
            raise RuntimeError('No confirmed bug-tainted resolver attempts were found')
        manifest = {
            'schema': 1,
            'type': DOCKER_DEPTH_RESOLVER_REFUND_MANIFEST_TYPE,
            'version': 1,
            'experiment_id': int(row['id']),
            'experiment_key': authority['experiment_key'],
            'source': authority['source'],
            'config_sha256': authority['config_sha256'],
            'ordered_queries_sha256': authority['ordered_queries_sha256'],
            'selector_sha256': authority['selector_sha256'],
            'provenance_policy_sha256': authority['provenance_policy_sha256'],
            'plan_sha256': str(row['plan_sha256']),
            'hold_reason_code': 'resolver_attempt_limit',
            'recovery_kind': DOCKER_DEPTH_RESOLVER_REFUND_KIND,
            'refund_attempts': DOCKER_DEPTH_RESOLVER_REFUND_ATTEMPTS,
            'evidence_log_name': 'dockerhub.log',
            'evidence_log_sha256': log_sha256,
            'entry_count': len(entries),
            'held_entry_count': sum(
                item['prior_work_state'] == 'held' for item in entries
            ),
            'selection_sha256': _canonical_sha256(entries),
            'entries': entries,
        }
        normalized, manifest_sha256 = validate_docker_depth_resolver_refund_manifest(
            manifest, experiment, provenance_policy_sha256,
        )
        conn.commit()
        return normalized, manifest_sha256
    except Exception:
        conn.rollback()
        raise


def apply_docker_depth_resolver_refund_manifest(
    db, experiment, provenance_policy_sha256, manifest, manifest_sha256,
    evidence_log_path,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    manifest, expected_sha256 = validate_docker_depth_resolver_refund_manifest(
        manifest, experiment, provenance_policy_sha256,
    )
    if str(manifest_sha256 or '') != expected_sha256:
        raise ValueError('Docker depth resolver refund manifest hash conflicts')
    _, current_log_sha256 = _docker_depth_resolver_refund_log(evidence_log_path)
    if current_log_sha256 != manifest['evidence_log_sha256']:
        raise RuntimeError('Docker depth resolver refund evidence log drifted')
    conn = _require_postgres_experiment_db(db, 'Docker depth resolver refund')
    now = datetime.now(timezone.utc).isoformat(timespec='seconds')
    try:
        row = _locked_experiment_row(conn, authority)
        if (
            int(row['id']) != manifest['experiment_id']
            or str(row['plan_sha256'] or '') != manifest['plan_sha256']
            or _experiment_fence_active(row)
        ):
            raise RuntimeError('Docker depth resolver refund experiment identity drifted')
        existing = conn.execute(
            '''SELECT * FROM docker_depth_resolver_attempt_refunds
                WHERE experiment_id = ? AND recovery_kind = ? ORDER BY id FOR UPDATE''',
            (row['id'], DOCKER_DEPTH_RESOLVER_REFUND_KIND),
        ).fetchall()
        if existing:
            expected_entries = {
                item['experiment_repository_id']: item for item in manifest['entries']
            }
            if (
                len(existing) != len(expected_entries)
                or any(
                    int(audit['experiment_repository_id']) not in expected_entries
                    or str(audit['manifest_sha256']) != expected_sha256
                    or str(audit['entry_evidence_sha256'])
                    != expected_entries[int(audit['experiment_repository_id'])][
                        'entry_evidence_sha256'
                    ]
                    for audit in existing
                )
            ):
                raise RuntimeError('Docker depth resolver refund audit conflicts')
            conn.commit()
            return {
                'experiment_id': int(row['id']),
                'refunded': 0,
                'duplicates': len(existing),
                'state': str(row['state']),
            }
        if (
            str(row['state']) != 'held'
            or str(row['hold_reason_code'] or '') != 'resolver_attempt_limit'
        ):
            raise RuntimeError('Docker depth resolver refund requires an attempt-limit hold')
        member_ids = [item['experiment_repository_id'] for item in manifest['entries']]
        placeholders = ','.join('?' for _ in member_ids)
        members = conn.execute(
            f'''SELECT member.*, queue.id AS effective_repository_queue_id,
                       queue.normalized_target
                  FROM docker_depth_experiment_repositories member
                  JOIN target_queue queue
                    ON queue.id = COALESCE(
                        member.replacement_repository_queue_id,
                        member.repository_queue_id
                    )
                 WHERE member.experiment_id = ? AND member.id IN ({placeholders})
                 ORDER BY member.id FOR UPDATE OF member, queue''',
            (row['id'], *member_ids),
        ).fetchall()
        if len(members) != len(member_ids):
            raise RuntimeError('Docker depth resolver refund membership set drifted')
        entries_by_id = {
            item['experiment_repository_id']: item for item in manifest['entries']
        }
        for member in members:
            member_id = int(member['id'])
            entry = entries_by_id.get(member_id)
            last_error = str(member['last_error_code'] or '')
            target = str(member['normalized_target'] or '')
            if (
                entry is None
                or int(member['effective_repository_queue_id'])
                != entry['repository_queue_id']
                or int(member['query_ordinal']) != entry['query_ordinal']
                or int(member['repository_rank']) != entry['repository_rank']
                or str(member['work_state']) != entry['prior_work_state']
                or int(member['resolver_attempts']) != entry['prior_resolver_attempts']
                or _docker_depth_resolver_refund_text_sha256(last_error)
                != entry['prior_error_code_sha256']
                or _docker_depth_resolver_refund_text_sha256(target)
                != entry['target_identity_sha256']
                or any(member[name] is not None for name in (
                    'resolver_owner', 'resolver_token', 'resolver_expires_at',
                ))
            ):
                raise RuntimeError('Docker depth resolver refund membership evidence drifted')
            cursor = conn.execute(
                '''UPDATE docker_depth_experiment_repositories
                      SET work_state = 'pending', resolver_attempts = ?,
                          resolver_due_at = NULL, last_error_code = NULL,
                          updated_at = ?
                    WHERE id = ? AND experiment_id = ? AND work_state = ?
                      AND resolver_attempts = ? AND resolver_owner IS NULL
                      AND resolver_token IS NULL AND resolver_expires_at IS NULL''',
                (
                    entry['next_resolver_attempts'], now, member_id, row['id'],
                    entry['prior_work_state'], entry['prior_resolver_attempts'],
                ),
            )
            if int(cursor.rowcount or 0) != 1:
                raise RuntimeError('Docker depth resolver refund lost its member fence')
            conn.execute(
                '''INSERT INTO docker_depth_resolver_attempt_refunds(
                       experiment_id, experiment_repository_id, repository_queue_id,
                       query_ordinal, repository_rank, recovery_kind, manifest_sha256,
                       entry_evidence_sha256, log_sha256, target_identity_sha256,
                       prior_error_code_sha256, prior_work_state, next_work_state,
                       prior_resolver_attempts, refund_attempts, next_resolver_attempts,
                       confirmed_bug_event_count, applied_at, created_at
                   ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)''',
                (
                    row['id'], member_id, entry['repository_queue_id'],
                    entry['query_ordinal'], entry['repository_rank'],
                    DOCKER_DEPTH_RESOLVER_REFUND_KIND, expected_sha256,
                    entry['entry_evidence_sha256'], manifest['evidence_log_sha256'],
                    entry['target_identity_sha256'], entry['prior_error_code_sha256'],
                    entry['prior_work_state'], entry['next_work_state'],
                    entry['prior_resolver_attempts'], entry['refund_attempts'],
                    entry['next_resolver_attempts'], entry['confirmed_bug_event_count'],
                    now, now,
                ),
            )
        cursor = conn.execute(
            '''UPDATE docker_depth_experiments
                  SET state = 'resolving', hold_reason_code = NULL, held_at = NULL,
                      updated_at = ?
                WHERE id = ? AND state = 'held'
                  AND hold_reason_code = 'resolver_attempt_limit'
                  AND fence_owner IS NULL AND fence_token IS NULL
                  AND fence_expires_at IS NULL''',
            (now, row['id']),
        )
        if int(cursor.rowcount or 0) != 1:
            raise RuntimeError('Docker depth resolver refund lost its experiment fence')
        refreshed = conn.execute(
            'SELECT * FROM docker_depth_experiments WHERE id = ? FOR UPDATE',
            (row['id'],),
        ).fetchone()
        drift = _persisted_experiment_drift_reason(db, refreshed, authority, now)
        if drift:
            raise RuntimeError(f'Docker depth resolver refund left authority drift: {drift}')
        conn.commit()
        return {
            'experiment_id': int(row['id']),
            'refunded': len(manifest['entries']),
            'duplicates': 0,
            'state': 'resolving',
        }
    except Exception:
        conn.rollback()
        raise


def _docker_depth_resolver_disposition_entry(member, candidates):
    target = str(member['normalized_target'] or '')
    if not target:
        raise RuntimeError('Docker depth resolver disposition target identity is absent')
    if (
        str(member['work_state'] or '') != 'held'
        or str(member['last_error_code'] or '') != 'resolver_attempt_limit'
        or int(member['resolver_attempts']) < DOCKER_DEPTH_RESOLVER_MAX_ATTEMPTS
        or int(member['selected_image_count']) != 0
        or any(member[name] is not None for name in (
            'resolver_owner', 'resolver_token', 'resolver_expires_at',
            'resolver_due_at',
        ))
    ):
        raise RuntimeError('Docker depth attempt-limit disposition state is invalid')
    replacement = next(
        (candidate for candidate in candidates if not candidate['conflict_reason']),
        None,
    )
    outcome = 'replaced' if replacement else 'skipped'
    attempts = int(member['resolver_attempts'])
    entry = {
        'experiment_repository_id': int(member['id']),
        'repository_queue_id': int(member['effective_repository_queue_id']),
        'query_ordinal': int(member['query_ordinal']),
        'repository_rank': int(member['repository_rank']),
        'disposition_kind': DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND,
        'outcome': outcome,
        'prior_work_state': 'held',
        'next_work_state': 'pending' if replacement else 'skipped',
        'prior_resolver_attempts': attempts,
        'next_resolver_attempts': 0 if replacement else attempts,
        'prior_error_code_sha256': _docker_depth_resolver_refund_text_sha256(
            member['last_error_code']
        ),
        'target_identity_sha256': _docker_depth_resolver_refund_text_sha256(target),
        'candidate_snapshot_sha256': _canonical_sha256(candidates),
        'inspected_candidate_count': len(candidates),
        'replacement_repository_queue_id': (
            replacement['repository_queue_id'] if replacement else None
        ),
        'replacement_eligibility_page_id': (
            replacement['eligibility_page_id'] if replacement else None
        ),
        'replacement_best_search_rank': (
            replacement['best_search_rank'] if replacement else None
        ),
        'replacement_target_identity_sha256': (
            replacement['target_identity_sha256'] if replacement else None
        ),
        'terminal_reason': (
            '' if replacement else DOCKER_DEPTH_REMOTE_UNAVAILABLE_SKIP_REASON
        ),
    }
    entry['entry_evidence_sha256'] = _canonical_sha256(entry)
    return entry


def validate_docker_depth_resolver_disposition_manifest(
    manifest, experiment=None, provenance_policy_sha256=None,
):
    expected_keys = {
        'schema', 'type', 'version', 'experiment_id', 'experiment_key', 'source',
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'hold_reason_code',
        'disposition_kind', 'entry_count', 'selection_sha256', 'entries',
    }
    if (
        not isinstance(manifest, dict)
        or set(manifest) != expected_keys
        or type(manifest.get('schema')) is not int
        or manifest.get('schema') != 1
        or type(manifest.get('version')) is not int
        or manifest.get('version') != 1
        or manifest.get('type') != DOCKER_DEPTH_RESOLVER_DISPOSITION_MANIFEST_TYPE
    ):
        raise ValueError('Docker depth resolver disposition manifest shape is invalid')
    _strict_identifier(manifest.get('experiment_key'), 'experiment_key')
    entries = manifest.get('entries')
    if not isinstance(entries, list) or len(entries) != 1:
        raise ValueError('Docker depth resolver disposition requires one reviewed entry')
    raw = entries[0]
    expected_entry_keys = {
        'experiment_repository_id', 'repository_queue_id', 'query_ordinal',
        'repository_rank', 'disposition_kind', 'outcome', 'prior_work_state',
        'next_work_state', 'prior_resolver_attempts', 'next_resolver_attempts',
        'prior_error_code_sha256', 'target_identity_sha256',
        'candidate_snapshot_sha256', 'inspected_candidate_count',
        'replacement_repository_queue_id', 'replacement_eligibility_page_id',
        'replacement_best_search_rank', 'replacement_target_identity_sha256',
        'terminal_reason', 'entry_evidence_sha256',
    }
    if not isinstance(raw, dict) or set(raw) != expected_entry_keys:
        raise ValueError('Docker depth resolver disposition entry shape is invalid')
    entry = copy.deepcopy(raw)
    _strict_positive_int(entry['experiment_repository_id'], 'experiment_repository_id')
    _strict_positive_int(entry['repository_queue_id'], 'repository_queue_id')
    _strict_nonnegative_int(entry['query_ordinal'], 'query_ordinal')
    _strict_positive_int(entry['repository_rank'], 'repository_rank')
    attempts = _strict_positive_int(
        entry['prior_resolver_attempts'], 'prior_resolver_attempts',
    )
    next_attempts = _strict_nonnegative_int(
        entry['next_resolver_attempts'], 'next_resolver_attempts',
    )
    inspected = _strict_nonnegative_int(
        entry['inspected_candidate_count'], 'inspected_candidate_count',
    )
    if inspected > 3000 or attempts < DOCKER_DEPTH_RESOLVER_MAX_ATTEMPTS:
        raise ValueError('Docker depth resolver disposition range is invalid')
    outcome = entry['outcome']
    replacement_fields = (
        'replacement_repository_queue_id', 'replacement_eligibility_page_id',
        'replacement_best_search_rank', 'replacement_target_identity_sha256',
    )
    if outcome == 'replaced':
        for name in replacement_fields[:3]:
            _strict_positive_int(entry[name], name)
        if (
            entry['next_work_state'] != 'pending'
            or next_attempts != 0
            or entry['terminal_reason'] != ''
            or not _valid_sha256(entry['replacement_target_identity_sha256'])
            or inspected < 1
        ):
            raise ValueError('Docker depth replacement disposition is invalid')
    elif outcome == 'skipped':
        if (
            any(entry[name] is not None for name in replacement_fields)
            or entry['next_work_state'] != 'skipped'
            or next_attempts != attempts
            or entry['terminal_reason'] != DOCKER_DEPTH_REMOTE_UNAVAILABLE_SKIP_REASON
        ):
            raise ValueError('Docker depth skip disposition is invalid')
    else:
        raise ValueError('Docker depth resolver disposition outcome is invalid')
    if (
        entry['disposition_kind'] != DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND
        or entry['prior_work_state'] != 'held'
        or any(not _valid_sha256(entry.get(name)) for name in (
            'prior_error_code_sha256', 'target_identity_sha256',
            'candidate_snapshot_sha256', 'entry_evidence_sha256',
        ))
    ):
        raise ValueError('Docker depth resolver disposition evidence is invalid')
    evidence = dict(entry)
    evidence.pop('entry_evidence_sha256')
    if entry['entry_evidence_sha256'] != _canonical_sha256(evidence):
        raise ValueError('Docker depth resolver disposition entry hash conflicts')
    hashes = (
        'config_sha256', 'ordered_queries_sha256', 'selector_sha256',
        'provenance_policy_sha256', 'plan_sha256', 'selection_sha256',
    )
    if any(not _valid_sha256(manifest.get(name)) for name in hashes):
        raise ValueError('Docker depth resolver disposition manifest hash is invalid')
    if (
        _strict_positive_int(manifest.get('experiment_id'), 'experiment_id') <= 0
        or manifest.get('source') != 'dockerhub'
        or manifest.get('hold_reason_code') != 'resolver_attempt_limit'
        or manifest.get('disposition_kind') != DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND
        or manifest.get('entry_count') != 1
        or manifest.get('selection_sha256') != _canonical_sha256(entries)
    ):
        raise ValueError('Docker depth resolver disposition authority is invalid')
    if experiment is not None:
        authority = _docker_depth_authority(
            experiment,
            provenance_policy_sha256 or manifest['provenance_policy_sha256'],
        )
        for manifest_name, authority_name in (
            ('experiment_key', 'experiment_key'), ('source', 'source'),
            ('config_sha256', 'config_sha256'),
            ('ordered_queries_sha256', 'ordered_queries_sha256'),
            ('selector_sha256', 'selector_sha256'),
            ('provenance_policy_sha256', 'provenance_policy_sha256'),
        ):
            if manifest[manifest_name] != authority[authority_name]:
                raise ValueError('Docker depth resolver disposition authority drifted')
    normalized = copy.deepcopy(manifest)
    normalized['entries'] = [entry]
    if normalized != manifest:
        raise ValueError('Docker depth resolver disposition manifest is not canonical')
    return normalized, _canonical_sha256(normalized)


def generate_docker_depth_resolver_disposition_manifest(
    db, experiment, provenance_policy_sha256,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    conn = _require_postgres_experiment_db(
        db, 'Docker depth resolver disposition planning',
    )
    try:
        row = _experiment_row(conn, authority, False)
        if (
            str(row['state']) != 'held'
            or str(row['hold_reason_code'] or '') != 'resolver_attempt_limit'
            or not _valid_sha256(row['plan_sha256'])
            or _experiment_fence_active(row)
        ):
            raise RuntimeError(
                'Docker depth resolver disposition requires an attempt-limit hold'
            )
        members = conn.execute(
            '''SELECT member.*, queue.id AS effective_repository_queue_id,
                      queue.normalized_target
                 FROM docker_depth_experiment_repositories member
                 JOIN target_queue queue ON queue.id = COALESCE(
                     member.replacement_repository_queue_id,
                     member.repository_queue_id
                 )
                WHERE member.experiment_id = ? AND member.work_state = 'held'
                  AND member.last_error_code = 'resolver_attempt_limit'
                ORDER BY member.id''',
            (row['id'],),
        ).fetchall()
        if len(members) != 1:
            raise RuntimeError(
                'Docker depth resolver disposition requires one held membership'
            )
        member = members[0]
        candidates = db._docker_depth_repository_replacement_candidates(
            row, member, authority, lock=False,
        )
        entry = _docker_depth_resolver_disposition_entry(member, candidates)
        manifest = {
            'schema': 1,
            'type': DOCKER_DEPTH_RESOLVER_DISPOSITION_MANIFEST_TYPE,
            'version': 1,
            'experiment_id': int(row['id']),
            'experiment_key': authority['experiment_key'],
            'source': authority['source'],
            'config_sha256': authority['config_sha256'],
            'ordered_queries_sha256': authority['ordered_queries_sha256'],
            'selector_sha256': authority['selector_sha256'],
            'provenance_policy_sha256': authority['provenance_policy_sha256'],
            'plan_sha256': str(row['plan_sha256']),
            'hold_reason_code': 'resolver_attempt_limit',
            'disposition_kind': DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND,
            'entry_count': 1,
            'selection_sha256': _canonical_sha256([entry]),
            'entries': [entry],
        }
        normalized, manifest_sha256 = (
            validate_docker_depth_resolver_disposition_manifest(
                manifest, experiment, provenance_policy_sha256,
            )
        )
        conn.commit()
        return normalized, manifest_sha256
    except Exception:
        conn.rollback()
        raise


def apply_docker_depth_resolver_disposition_manifest(
    db, experiment, provenance_policy_sha256, manifest, manifest_sha256,
):
    authority = _docker_depth_authority(experiment, provenance_policy_sha256)
    manifest, expected_sha256 = validate_docker_depth_resolver_disposition_manifest(
        manifest, experiment, provenance_policy_sha256,
    )
    if str(manifest_sha256 or '') != expected_sha256:
        raise ValueError('Docker depth resolver disposition manifest hash conflicts')
    conn = _require_postgres_experiment_db(db, 'Docker depth resolver disposition')
    now = datetime.now(timezone.utc).isoformat(timespec='seconds')
    entry = manifest['entries'][0]
    try:
        row = _locked_experiment_row(conn, authority)
        if (
            int(row['id']) != manifest['experiment_id']
            or str(row['plan_sha256'] or '') != manifest['plan_sha256']
            or _experiment_fence_active(row)
        ):
            raise RuntimeError('Docker depth resolver disposition identity drifted')
        existing = conn.execute(
            '''SELECT * FROM docker_depth_resolver_dispositions
                WHERE experiment_repository_id = ? AND disposition_kind = ?
                FOR UPDATE''',
            (
                entry['experiment_repository_id'],
                DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND,
            ),
        ).fetchone()
        if existing:
            if (
                int(existing['experiment_id']) != int(row['id'])
                or str(existing['manifest_sha256']) != expected_sha256
                or str(existing['entry_evidence_sha256'])
                != entry['entry_evidence_sha256']
                or str(existing['outcome']) != entry['outcome']
            ):
                raise RuntimeError('Docker depth resolver disposition audit conflicts')
            conn.commit()
            return {
                'experiment_id': int(row['id']), 'applied': 0, 'duplicates': 1,
                'outcome': str(existing['outcome']), 'state': str(row['state']),
            }
        if (
            str(row['state']) != 'held'
            or str(row['hold_reason_code'] or '') != 'resolver_attempt_limit'
        ):
            raise RuntimeError(
                'Docker depth resolver disposition requires an attempt-limit hold'
            )
        member = conn.execute(
            '''SELECT member.*, queue.id AS effective_repository_queue_id,
                      queue.normalized_target
                 FROM docker_depth_experiment_repositories member
                 JOIN target_queue queue ON queue.id = COALESCE(
                     member.replacement_repository_queue_id,
                     member.repository_queue_id
                 )
                WHERE member.id = ? AND member.experiment_id = ?
                FOR UPDATE OF member, queue''',
            (entry['experiment_repository_id'], row['id']),
        ).fetchone()
        if not member:
            raise RuntimeError('Docker depth resolver disposition membership is absent')
        target = str(member['normalized_target'] or '')
        if (
            int(member['effective_repository_queue_id']) != entry['repository_queue_id']
            or int(member['query_ordinal']) != entry['query_ordinal']
            or int(member['repository_rank']) != entry['repository_rank']
            or str(member['work_state']) != entry['prior_work_state']
            or int(member['resolver_attempts']) != entry['prior_resolver_attempts']
            or str(member['last_error_code'] or '') != 'resolver_attempt_limit'
            or int(member['selected_image_count']) != 0
            or _docker_depth_resolver_refund_text_sha256(target)
            != entry['target_identity_sha256']
            or _docker_depth_resolver_refund_text_sha256(member['last_error_code'])
            != entry['prior_error_code_sha256']
            or any(member[name] is not None for name in (
                'resolver_owner', 'resolver_token', 'resolver_expires_at',
                'resolver_due_at',
            ))
        ):
            raise RuntimeError('Docker depth resolver disposition evidence drifted')
        if conn.execute(
            '''SELECT 1 FROM docker_depth_experiment_selections
               WHERE experiment_repository_id = ? LIMIT 1''',
            (member['id'],),
        ).fetchone():
            raise RuntimeError('Docker depth resolver disposition cannot replace selected work')
        candidates = db._docker_depth_repository_replacement_candidates(
            row, member, authority, lock=True,
        )
        current_entry = _docker_depth_resolver_disposition_entry(member, candidates)
        if current_entry != entry:
            raise RuntimeError('Docker depth resolver disposition selection drifted after review')
        for candidate in candidates:
            if not candidate['conflict_reason']:
                break
            db._record_docker_depth_candidate_skip_locked(
                row, member, candidate['repository_queue_id'], 'repository',
                candidate['best_search_rank'],
                {'repository_queue_id': candidate['repository_queue_id']},
                candidate['conflict_reason'], now,
            )
        current_queue_id = int(member['effective_repository_queue_id'])
        db._record_docker_depth_candidate_skip_locked(
            row, member, current_queue_id, 'repository',
            int(member['replacement_count']) + 1,
            {'repository_queue_id': current_queue_id},
            DOCKER_DEPTH_REMOTE_UNAVAILABLE_SKIP_REASON, now,
        )
        replacement = next(
            (candidate for candidate in candidates if not candidate['conflict_reason']),
            None,
        )
        if replacement:
            previous_hash = str(member['replacement_evidence_sha256'] or '')
            replacement_document = {
                'schema': 1,
                'type': 'docker-depth-repository-replacement-v1',
                'experiment_id': int(row['id']),
                'experiment_repository_id': int(member['id']),
                'replacement_number': int(member['replacement_count']) + 1,
                'from_repository_queue_id': current_queue_id,
                'to_repository_queue_id': replacement['repository_queue_id'],
                'eligibility_page_id': replacement['eligibility_page_id'],
                'best_search_rank': replacement['best_search_rank'],
                'previous_evidence_sha256': previous_hash,
                'reason_code': DOCKER_DEPTH_REMOTE_UNAVAILABLE_SKIP_REASON,
            }
            replacement_sha256 = _canonical_sha256(replacement_document)
            cursor = conn.execute(
                '''UPDATE docker_depth_experiment_repositories
                      SET replacement_repository_queue_id = ?,
                          replacement_eligibility_page_id = ?,
                          replacement_count = replacement_count + 1,
                          replacement_evidence_sha256 = ?, work_state = 'pending',
                          resolver_attempts = 0, resolver_due_at = NULL,
                          last_error_code = 'repository_candidate_replaced',
                          resolved_at = NULL, updated_at = ?
                    WHERE id = ? AND experiment_id = ? AND work_state = 'held'
                      AND resolver_attempts = ? AND resolver_owner IS NULL
                      AND resolver_token IS NULL AND resolver_expires_at IS NULL''',
                (
                    replacement['repository_queue_id'],
                    replacement['eligibility_page_id'], replacement_sha256, now,
                    member['id'], row['id'], entry['prior_resolver_attempts'],
                ),
            )
        else:
            cursor = conn.execute(
                '''UPDATE docker_depth_experiment_repositories
                      SET work_state = 'skipped', resolver_due_at = NULL,
                          last_error_code = ?, selected_image_count = 0,
                          resolved_at = ?, updated_at = ?
                    WHERE id = ? AND experiment_id = ? AND work_state = 'held'
                      AND resolver_attempts = ? AND resolver_owner IS NULL
                      AND resolver_token IS NULL AND resolver_expires_at IS NULL''',
                (
                    DOCKER_DEPTH_REMOTE_UNAVAILABLE_SKIP_REASON, now, now,
                    member['id'], row['id'], entry['prior_resolver_attempts'],
                ),
            )
        if int(cursor.rowcount or 0) != 1:
            raise RuntimeError('Docker depth resolver disposition lost its member fence')
        resume = conn.execute(
            '''UPDATE docker_depth_experiments
                  SET state = 'resolving', hold_reason_code = NULL, held_at = NULL,
                      updated_at = ?
                WHERE id = ? AND state = 'held'
                  AND hold_reason_code = 'resolver_attempt_limit'
                  AND fence_owner IS NULL AND fence_token IS NULL
                  AND fence_expires_at IS NULL''',
            (now, row['id']),
        )
        if int(resume.rowcount or 0) != 1:
            raise RuntimeError('Docker depth resolver disposition lost its experiment fence')
        if not replacement:
            refreshed_member = conn.execute(
                'SELECT * FROM docker_depth_experiment_repositories WHERE id = ?',
                (member['id'],),
            ).fetchone()
            db._finalize_docker_depth_query_breadth_locked(row, refreshed_member, now)
        refreshed = conn.execute(
            'SELECT * FROM docker_depth_experiments WHERE id = ? FOR UPDATE',
            (row['id'],),
        ).fetchone()
        refreshed, selection_reason = db._freeze_docker_depth_runtime_selection_locked(
            refreshed, authority, now,
        )
        if selection_reason:
            raise RuntimeError(
                f'Docker depth resolver disposition selection drift: {selection_reason}'
            )
        drift = _persisted_experiment_drift_reason(db, refreshed, authority, now)
        if drift:
            raise RuntimeError(
                f'Docker depth resolver disposition left authority drift: {drift}'
            )
        refreshed = db._advance_docker_depth_experiment_state_locked(refreshed, now)
        conn.execute(
            '''INSERT INTO docker_depth_resolver_dispositions(
                   experiment_id, experiment_repository_id,
                   prior_repository_queue_id, replacement_repository_queue_id,
                   replacement_eligibility_page_id, replacement_best_search_rank,
                   query_ordinal, repository_rank, disposition_kind, outcome,
                   manifest_sha256, entry_evidence_sha256,
                   candidate_snapshot_sha256, prior_target_identity_sha256,
                   replacement_target_identity_sha256, prior_error_code_sha256,
                   prior_work_state, next_work_state, prior_resolver_attempts,
                   next_resolver_attempts, applied_at, created_at
               ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)''',
            (
                row['id'], member['id'], entry['repository_queue_id'],
                entry['replacement_repository_queue_id'],
                entry['replacement_eligibility_page_id'],
                entry['replacement_best_search_rank'], entry['query_ordinal'],
                entry['repository_rank'], DOCKER_DEPTH_RESOLVER_DISPOSITION_KIND,
                entry['outcome'], expected_sha256, entry['entry_evidence_sha256'],
                entry['candidate_snapshot_sha256'], entry['target_identity_sha256'],
                entry['replacement_target_identity_sha256'],
                entry['prior_error_code_sha256'], entry['prior_work_state'],
                entry['next_work_state'], entry['prior_resolver_attempts'],
                entry['next_resolver_attempts'], now, now,
            ),
        )
        conn.commit()
        return {
            'experiment_id': int(row['id']), 'applied': 1, 'duplicates': 0,
            'outcome': entry['outcome'], 'state': str(refreshed['state']),
        }
    except Exception:
        conn.rollback()
        raise