sable-sphynx 0.7.0.dev0__py3-none-any.whl

sphynx/dataset_v3.py

@@ -0,0 +1,999 @@
+"""Sphynx-owned port of the source contracts; no sibling runtime dependency."""
+from __future__ import annotations
+from typing import Any
+JsonValue = Any
+"""Stable public types and enumerations for the offline RAG DatasetV3 contract."""
+from dataclasses import dataclass, field
+from typing import Literal
+DATASET_V3_SCHEMA_VERSION = 'sable.rag.dataset.v3'
+CUSTOMER_REGISTRY_SCHEMA_VERSION = 'sable.rag.customer-registry.v1'
+Partition = Literal['calibration', 'development', 'protected_holdout', 'validation']
+Answerability = Literal['answerable', 'unsupported']
+ExpectedBehavior = Literal['answer', 'abstain', 'no_rag']
+Severity = Literal['critical', 'high', 'low', 'medium']
+Requirement = Literal['optional', 'required']
+JudgmentStatus = Literal['judged', 'unknown']
+Authority = Literal['primary', 'secondary', 'unknown']
+Currentness = Literal['current', 'stale', 'superseded', 'unknown']
+HardNegativeType = Literal['authority_conflict', 'lexical_overlap', 'near_duplicate', 'negation_flip', 'scope_mismatch', 'sibling_section', 'stale', 'unsupported_distractor']
+PARTITIONS = frozenset({'calibration', 'development', 'protected_holdout', 'validation'})
+ANSWERABILITY = frozenset({'answerable', 'unsupported'})
+EXPECTED_BEHAVIORS = frozenset({'answer', 'abstain', 'no_rag'})
+SEVERITIES = frozenset({'critical', 'high', 'low', 'medium'})
+REQUIREMENTS = frozenset({'optional', 'required'})
+JUDGMENT_STATUSES = frozenset({'judged', 'unknown'})
+AUTHORITIES = frozenset({'primary', 'secondary', 'unknown'})
+CURRENTNESS = frozenset({'current', 'stale', 'superseded', 'unknown'})
+HARD_NEGATIVE_TYPES = frozenset({'authority_conflict', 'lexical_overlap', 'near_duplicate', 'negation_flip', 'scope_mismatch', 'sibling_section', 'stale', 'unsupported_distractor'})
+
+class DatasetV3Error(ValueError):
+    """Raised when DatasetV3 violates a structural or truth invariant."""
+
+class CustomerRegistryError(ValueError):
+    """Raised when the customer registry is incomplete or inconsistent."""
+
+@dataclass(frozen=True, slots=True)
+class TaskIdentity:
+    """Minimal task identity used by split and report routing."""
+    task_id: str
+    customer_id: str
+    partition: Partition
+    cluster_id: str
+    def __post_init__(self) -> None:
+        v3_id(self.task_id, 'task ID')
+        v3_id(self.customer_id, 'customer ID')
+        v3_enum(self.partition, PARTITIONS, 'partition')
+        v3_id(self.cluster_id, 'cluster ID')
+
+
+@dataclass(frozen=True, slots=True)
+class DatasetV3:
+    """Validated normalized dataset and its immutable task identities."""
+    _value_bytes: bytes
+    dataset_id: str
+    version: str
+    default_relevance_threshold: int
+    tasks: tuple[TaskIdentity, ...]
+
+    def __post_init__(self) -> None:
+        from ._track_capture import strict_json
+        if not isinstance(self._value_bytes, (bytes, bytearray, memoryview)):
+            raise DatasetV3Error('dataset content must be bytes')
+        encoded = bytes(self._value_bytes)
+        try:
+            expected = _validate_dataset_v3_fields(strict_json(encoded))
+        except ValueError as error:
+            raise DatasetV3Error('invalid committed dataset content') from error
+        if not isinstance(self.tasks, (list, tuple)) or any(type(item) is not TaskIdentity for item in self.tasks):
+            raise DatasetV3Error('dataset tasks must be task identities')
+        tasks = tuple(self.tasks)
+        v3_integer(self.default_relevance_threshold, 'default relevance threshold', minimum=1)
+        if (self.dataset_id, self.version, self.default_relevance_threshold, tasks) != expected[1:]:
+            raise DatasetV3Error('exposed dataset records differ from committed dataset bytes')
+        object.__setattr__(self, '_value_bytes', encoded)
+        object.__setattr__(self, 'tasks', tasks)
+
+    @property
+    def value(self):
+        return json.loads(self._value_bytes)
+
+@dataclass(frozen=True, slots=True)
+class CustomerRecord:
+    """One privacy-safe customer registry record."""
+    customer_id: str
+    display_name: str
+    pack_status: Literal['available', 'missing']
+    pack_path: str | None
+    pack_manifest_sha256: str | None
+    blockers: tuple[str, ...]
+    def __post_init__(self) -> None:
+        registry_id(self.customer_id, 'customer ID')
+        registry_text(self.display_name, 'display name')
+        if not isinstance(self.blockers, (list, tuple)):
+            raise CustomerRegistryError('blockers must be a list or tuple')
+        _, _, _, blockers = registry_validate_pack({'status': self.pack_status, 'path': self.pack_path, 'manifest_sha256': self.pack_manifest_sha256, 'blockers': list(self.blockers)}, self.customer_id, 'customer pack')
+        object.__setattr__(self, 'blockers', blockers)
+
+
+@dataclass(frozen=True, slots=True, init=False)
+class CustomerRegistry:
+    """Validated registry with detached reads of an immutable source snapshot."""
+    _value_bytes: bytes
+    customers: tuple[CustomerRecord, ...]
+
+    def __init__(self, value=None, customers=(), *, _value_bytes=None):
+        from ._track_capture import strict_json
+        if _value_bytes is not None:
+            if not isinstance(_value_bytes, (bytes, bytearray, memoryview)):
+                raise CustomerRegistryError('committed registry content must be bytes')
+            encoded = bytes(_value_bytes)
+            try:
+                committed = strict_json(encoded)
+                if value is not None:
+                    _validate_customer_registry_fields(value)
+                    supplied_json = json.dumps(registry_clone(value), allow_nan=False, ensure_ascii=False, sort_keys=True)
+                    committed_json = json.dumps(committed, allow_nan=False, ensure_ascii=False, sort_keys=True)
+                    if supplied_json != committed_json:
+                        raise CustomerRegistryError('registry mapping differs from committed bytes')
+                value = committed
+            except ValueError as error:
+                raise CustomerRegistryError('invalid committed registry JSON') from error
+        else:
+            encoded = json.dumps(registry_clone(value), allow_nan=False, ensure_ascii=False, sort_keys=True).encode('utf-8')
+            value = strict_json(encoded)
+        _, expected = _validate_customer_registry_fields(value)
+        if not isinstance(customers, (list, tuple)) or any(type(item) is not CustomerRecord for item in customers):
+            raise CustomerRegistryError('customers must be customer records')
+        records = tuple(customers)
+        if records != expected:
+            raise CustomerRegistryError('exposed customer records differ from committed registry bytes')
+        object.__setattr__(self, '_value_bytes', encoded)
+        object.__setattr__(self, 'customers', records)
+
+    @property
+    def value(self):
+        return json.loads(self._value_bytes)
+
+    @property
+    def customer_ids(self) -> tuple[str, ...]:
+        return tuple(customer.customer_id for customer in self.customers)
+
+@dataclass(frozen=True, slots=True)
+class PrivacyFinding:
+    """A redacted prohibited-data finding; the matched value is never retained."""
+    category: str
+    path: str
+    value_sha256: str
+
+@dataclass(frozen=True, slots=True)
+class ReadinessBlocker:
+    """One named reason an evaluation or level cannot be scored."""
+    code: str
+    scope: Literal['data', 'level1', 'level2', 'level3']
+    detail: str
+
+@dataclass(frozen=True, slots=True)
+class ReadinessReport:
+    """Objective data maturity plus execution blockers that do not fabricate metrics."""
+    status: Literal['blocked', 'decision_grade', 'draft', 'pilot_ready']
+    independent_clusters: int
+    double_labeled_cluster_rate: float
+    blockers: tuple[ReadinessBlocker, ...]
+    coverage: dict[str, bool]
+    coverage_counts: dict[str, int] = field(default_factory=dict)
+
+    @property
+    def quality_metrics_allowed(self) -> bool:
+        return not any((blocker.scope == 'data' for blocker in self.blockers))
+
+@dataclass(frozen=True, slots=True)
+class PackIntake:
+    """Validated, content-bound pack intake result without raw customer content."""
+    customer_id: str
+    pack_id: str
+    manifest_sha256: str
+    dataset_sha256: str
+    dataset: DatasetV3
+    readiness: ReadinessReport
+
+"""Strict source-grounded DatasetV3 validation and split-leakage enforcement."""
+import hashlib
+import json
+import math
+import re
+from collections.abc import Mapping
+from datetime import datetime
+from pathlib import Path
+from typing import Any, cast
+v3_ID = re.compile('[a-z0-9][a-z0-9._:-]{0,127}')
+v3_SHA256 = re.compile('[0-9a-f]{64}')
+
+def v3_object(value: object, context: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping) or any((not isinstance(key, str) for key in value)):
+        raise DatasetV3Error(f'{context} must be an object with string keys')
+    return cast('Mapping[str, object]', value)
+
+def v3_exact(value: Mapping[str, object], fields: frozenset[str], context: str) -> None:
+    missing = sorted(fields - value.keys())
+    extra = sorted(value.keys() - fields)
+    if missing or extra:
+        raise DatasetV3Error(f'{context} keys differ; missing={missing}, extra={extra}')
+
+def v3_array(value: object, context: str, *, nonempty: bool=False) -> list[object]:
+    if not isinstance(value, list) or (nonempty and (not value)):
+        qualifier = 'non-empty ' if nonempty else ''
+        raise DatasetV3Error(f'{context} must be a {qualifier}array')
+    return cast('list[object]', value)
+
+def v3_text(value: object, context: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise DatasetV3Error(f'{context} must be non-empty text')
+    return value
+
+def v3_optional_text(value: object, context: str) -> str | None:
+    return None if value is None else v3_text(value, context)
+
+def v3_id(value: object, context: str) -> str:
+    result = v3_text(value, context)
+    if v3_ID.fullmatch(result) is None:
+        raise DatasetV3Error(f'{context} must be a privacy-safe stable identifier')
+    return result
+
+def v3_digest(value: object, context: str) -> str:
+    result = v3_text(value, context)
+    if v3_SHA256.fullmatch(result) is None:
+        raise DatasetV3Error(f'{context} must be a lowercase SHA-256 digest')
+    return result
+
+def v3_enum(value: object, choices: frozenset[str], context: str) -> str:
+    result = v3_text(value, context)
+    if result not in choices:
+        raise DatasetV3Error(f"{context} must be one of {', '.join(sorted(choices))}")
+    return result
+
+def v3_boolean(value: object, context: str) -> bool:
+    if not isinstance(value, bool):
+        raise DatasetV3Error(f'{context} must be boolean')
+    return value
+
+def v3_integer(value: object, context: str, *, minimum: int=0) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise DatasetV3Error(f'{context} must be an integer >= {minimum}')
+    return value
+
+def v3_finite(value: object, context: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise DatasetV3Error(f'{context} must be numeric')
+    result = float(value)
+    if not math.isfinite(result):
+        raise DatasetV3Error(f'{context} must be finite')
+    return result
+
+def v3_timestamp(value: object, context: str) -> str:
+    result = v3_text(value, context)
+    try:
+        parsed = datetime.fromisoformat(result.replace('Z', '+00:00'))
+    except ValueError as error:
+        raise DatasetV3Error(f'{context} must be an ISO-8601 timestamp') from error
+    if parsed.tzinfo is None:
+        raise DatasetV3Error(f'{context} must include a timezone')
+    return result
+
+def v3_strings(value: object, context: str, *, nonempty: bool=False, identifiers: bool=False) -> tuple[str, ...]:
+    values = v3_array(value, context, nonempty=nonempty)
+    converted = tuple((v3_id(item, f'{context}[{index}]') if identifiers else v3_text(item, f'{context}[{index}]') for index, item in enumerate(values)))
+    if len(converted) != len(set(converted)):
+        raise DatasetV3Error(f'{context} must contain unique values')
+    return converted
+
+def v3_clone_json(value: object) -> dict[str, JsonValue]:
+    try:
+        encoded = json.dumps(value, allow_nan=False, ensure_ascii=False, sort_keys=True)
+        loaded: Any = json.loads(encoded)
+    except (TypeError, ValueError) as error:
+        raise DatasetV3Error('dataset must contain only finite JSON values') from error
+    if not isinstance(loaded, dict):
+        raise DatasetV3Error('dataset must be an object')
+    return cast('dict[str, JsonValue]', loaded)
+
+def v3_validate_versions(raw: object, context: str) -> None:
+    value = v3_object(raw, context)
+    v3_exact(value, frozenset({'corpus', 'index', 'chunking', 'embedding'}), context)
+    for field in ('corpus', 'index', 'chunking', 'embedding'):
+        v3_text(value[field], f'{context}.{field}')
+
+def v3_validate_context(raw: object, context: str) -> None:
+    for index, turn_raw in enumerate(v3_array(raw, context)):
+        turn_context = f'{context}[{index}]'
+        turn = v3_object(turn_raw, turn_context)
+        v3_exact(turn, frozenset({'role', 'text'}), turn_context)
+        v3_enum(turn['role'], frozenset({'assistant', 'user'}), f'{turn_context}.role')
+        v3_text(turn['text'], f'{turn_context}.text')
+
+def v3_validate_leakage_keys(raw: object, context: str) -> dict[str, tuple[str, ...]]:
+    value = v3_object(raw, context)
+    fields = frozenset({'source_family_ids', 'document_revision_family_ids', 'conversation_case_id', 'query_family_id', 'paraphrase_family_id', 'near_duplicate_family_ids'})
+    v3_exact(value, fields, context)
+    return {'source_family': v3_strings(value['source_family_ids'], f'{context}.source_family_ids', nonempty=True, identifiers=True), 'document_revision_family': v3_strings(value['document_revision_family_ids'], f'{context}.document_revision_family_ids', nonempty=True, identifiers=True), 'conversation_case': (v3_id(value['conversation_case_id'], f'{context}.conversation_case_id'),), 'query_family': (v3_id(value['query_family_id'], f'{context}.query_family_id'),), 'paraphrase_family': (v3_id(value['paraphrase_family_id'], f'{context}.paraphrase_family_id'),), 'near_duplicate_family': v3_strings(value['near_duplicate_family_ids'], f'{context}.near_duplicate_family_ids', identifiers=True)}
+
+def v3_validate_source_spans(raw: object, context: str, leakage_keys: dict[str, tuple[str, ...]]) -> set[str]:
+    spans = v3_array(raw, context, nonempty=True)
+    span_ids: set[str] = set()
+    for index, span_raw in enumerate(spans):
+        span_context = f'{context}[{index}]'
+        span = v3_object(span_raw, span_context)
+        v3_exact(span, frozenset({'source_span_id', 'document_id', 'source_family_id', 'document_revision_family_id', 'content', 'content_sha256', 'start', 'end', 'exact_text', 'authority', 'currentness', 'scope_tags'}), span_context)
+        span_id = v3_id(span['source_span_id'], f'{span_context}.source_span_id')
+        if span_id in span_ids:
+            raise DatasetV3Error(f'{context} contains duplicate source_span_id {span_id}')
+        span_ids.add(span_id)
+        v3_id(span['document_id'], f'{span_context}.document_id')
+        source_family = v3_id(span['source_family_id'], f'{span_context}.source_family_id')
+        revision_family = v3_id(span['document_revision_family_id'], f'{span_context}.document_revision_family_id')
+        if source_family not in leakage_keys['source_family']:
+            raise DatasetV3Error(f'{span_context}.source_family_id is absent from leakage_keys')
+        if revision_family not in leakage_keys['document_revision_family']:
+            raise DatasetV3Error(f'{span_context}.document_revision_family_id is absent from leakage_keys')
+        content = v3_text(span['content'], f'{span_context}.content')
+        expected_hash = hashlib.sha256(content.encode('utf-8')).hexdigest()
+        if v3_digest(span['content_sha256'], f'{span_context}.content_sha256') != expected_hash:
+            raise DatasetV3Error(f'{span_context}.content_sha256 does not bind content')
+        start = v3_integer(span['start'], f'{span_context}.start')
+        end = v3_integer(span['end'], f'{span_context}.end', minimum=1)
+        exact_text = v3_text(span['exact_text'], f'{span_context}.exact_text')
+        if end <= start or end > len(content) or content[start:end] != exact_text:
+            raise DatasetV3Error(f'{span_context} source-span bounds do not match exact_text')
+        v3_enum(span['authority'], AUTHORITIES, f'{span_context}.authority')
+        v3_enum(span['currentness'], CURRENTNESS, f'{span_context}.currentness')
+        v3_strings(span['scope_tags'], f'{span_context}.scope_tags', identifiers=True)
+    return span_ids
+
+def v3_validate_judgments(raw: object, context: str) -> tuple[int, ...]:
+    judgments = v3_array(raw, context)
+    annotators: set[str] = set()
+    grades: list[int] = []
+    for index, judgment_raw in enumerate(judgments):
+        judgment_context = f'{context}[{index}]'
+        judgment = v3_object(judgment_raw, judgment_context)
+        v3_exact(judgment, frozenset({'annotator_id', 'grade', 'rationale', 'created_at'}), judgment_context)
+        annotator = v3_id(judgment['annotator_id'], f'{judgment_context}.annotator_id')
+        if annotator in annotators:
+            raise DatasetV3Error(f'{context} contains a duplicate annotator')
+        annotators.add(annotator)
+        grade = v3_integer(judgment['grade'], f'{judgment_context}.grade')
+        if grade > 3:
+            raise DatasetV3Error(f'{judgment_context}.grade must be a qrel from 0 through 3')
+        grades.append(grade)
+        v3_text(judgment['rationale'], f'{judgment_context}.rationale')
+        v3_timestamp(judgment['created_at'], f'{judgment_context}.created_at')
+    return tuple(grades)
+
+def v3_validate_adjudication(raw: object, context: str, qrel: int) -> None:
+    value = v3_object(raw, context)
+    v3_exact(value, frozenset({'adjudicator_id', 'grade', 'rationale'}), context)
+    v3_id(value['adjudicator_id'], f'{context}.adjudicator_id')
+    if v3_integer(value['grade'], f'{context}.grade') != qrel:
+        raise DatasetV3Error(f'{context}.grade must equal final qrel')
+    v3_text(value['rationale'], f'{context}.rationale')
+
+def v3_validate_candidates(raw: object, context: str, source_span_ids: set[str]) -> tuple[set[str], dict[str, set[str]], dict[str, set[str]], tuple[int | None, ...]]:
+    candidates = v3_array(raw, context, nonempty=True)
+    candidate_ids: set[str] = set()
+    group_links: dict[str, set[str]] = {}
+    span_links: dict[str, set[str]] = {}
+    qrels: list[int | None] = []
+    for index, candidate_raw in enumerate(candidates):
+        candidate_context = f'{context}[{index}]'
+        candidate = v3_object(candidate_raw, candidate_context)
+        v3_exact(candidate, frozenset({'candidate_id', 'document_id', 'chunk_id', 'input', 'input_sha256', 'dense_rank', 'dense_score', 'judgment_status', 'qrel', 'qrel_rationale', 'judgment_blocker', 'judgments', 'adjudication', 'evidence_group_ids', 'source_span_ids', 'authority', 'currentness', 'scope_tags', 'hard_negative_types', 'duplicate_of_candidate_id'}), candidate_context)
+        candidate_id = v3_id(candidate['candidate_id'], f'{candidate_context}.candidate_id')
+        if candidate_id in candidate_ids:
+            raise DatasetV3Error(f'{context} contains duplicate candidate_id {candidate_id}')
+        candidate_ids.add(candidate_id)
+        v3_id(candidate['document_id'], f'{candidate_context}.document_id')
+        v3_id(candidate['chunk_id'], f'{candidate_context}.chunk_id')
+        candidate_input = v3_text(candidate['input'], f'{candidate_context}.input')
+        expected_hash = hashlib.sha256(candidate_input.encode('utf-8')).hexdigest()
+        if v3_digest(candidate['input_sha256'], f'{candidate_context}.input_sha256') != expected_hash:
+            raise DatasetV3Error(f'{candidate_context}.input_sha256 does not bind input')
+        if v3_integer(candidate['dense_rank'], f'{candidate_context}.dense_rank', minimum=1) != index + 1:
+            raise DatasetV3Error(f'{candidate_context}.dense_rank must equal {index + 1}')
+        v3_finite(candidate['dense_score'], f'{candidate_context}.dense_score')
+        status = v3_enum(candidate['judgment_status'], JUDGMENT_STATUSES, f'{candidate_context}.judgment_status')
+        grades = v3_validate_judgments(candidate['judgments'], f'{candidate_context}.judgments')
+        if status == 'judged':
+            qrel = v3_integer(candidate['qrel'], f'{candidate_context}.qrel')
+            if qrel > 3:
+                raise DatasetV3Error(f'{candidate_context}.qrel must be from 0 through 3')
+            v3_text(candidate['qrel_rationale'], f'{candidate_context}.qrel_rationale')
+            if candidate['judgment_blocker'] is not None or not grades:
+                raise DatasetV3Error(f'{candidate_context} judged qrel needs labels and cannot have a blocker')
+            if len(set(grades)) > 1 and candidate['adjudication'] is None:
+                raise DatasetV3Error(f'{candidate_context} label disagreement needs adjudication')
+            if candidate['adjudication'] is not None:
+                v3_validate_adjudication(candidate['adjudication'], f'{candidate_context}.adjudication', qrel)
+            elif any((grade != qrel for grade in grades)):
+                raise DatasetV3Error(f'{candidate_context}.qrel must equal its judgment')
+            qrels.append(qrel)
+        else:
+            if candidate['qrel'] is not None or candidate['qrel_rationale'] is not None or candidate['adjudication'] is not None or grades:
+                raise DatasetV3Error(f'{candidate_context} unknown qrel cannot imply a grade')
+            v3_text(candidate['judgment_blocker'], f'{candidate_context}.judgment_blocker')
+            qrels.append(None)
+        groups = set(v3_strings(candidate['evidence_group_ids'], f'{candidate_context}.evidence_group_ids', identifiers=True))
+        spans = set(v3_strings(candidate['source_span_ids'], f'{candidate_context}.source_span_ids', identifiers=True))
+        unknown_spans = spans - source_span_ids
+        if unknown_spans:
+            raise DatasetV3Error(f'{candidate_context} references unknown source spans')
+        group_links[candidate_id] = groups
+        span_links[candidate_id] = spans
+        v3_enum(candidate['authority'], AUTHORITIES, f'{candidate_context}.authority')
+        v3_enum(candidate['currentness'], CURRENTNESS, f'{candidate_context}.currentness')
+        v3_strings(candidate['scope_tags'], f'{candidate_context}.scope_tags', identifiers=True)
+        hard_negatives = v3_strings(candidate['hard_negative_types'], f'{candidate_context}.hard_negative_types', identifiers=True)
+        if any((item not in HARD_NEGATIVE_TYPES for item in hard_negatives)):
+            raise DatasetV3Error(f'{candidate_context}.hard_negative_types is unsupported')
+        duplicate = v3_optional_text(candidate['duplicate_of_candidate_id'], f'{candidate_context}.duplicate_of_candidate_id')
+        if duplicate == candidate_id:
+            raise DatasetV3Error(f'{candidate_context} cannot duplicate itself')
+    for index, candidate_raw in enumerate(candidates):
+        candidate = v3_object(candidate_raw, f'{context}[{index}]')
+        raw_duplicate = candidate['duplicate_of_candidate_id']
+        if raw_duplicate is not None and raw_duplicate not in candidate_ids:
+            raise DatasetV3Error(f'{context}[{index}] duplicate target is not in the frozen pool')
+    return (candidate_ids, group_links, span_links, tuple(qrels))
+
+def v3_validate_evidence_groups(raw: object, context: str, candidate_ids: set[str], source_span_ids: set[str], candidate_group_links: dict[str, set[str]], candidate_span_links: dict[str, set[str]]) -> tuple[int, set[str]]:
+    groups = v3_array(raw, context)
+    group_ids: set[str] = set()
+    required_count = 0
+    for index, group_raw in enumerate(groups):
+        group_context = f'{context}[{index}]'
+        group = v3_object(group_raw, group_context)
+        v3_exact(group, frozenset({'evidence_group_id', 'description', 'requirement', 'weight', 'acceptable_candidate_ids', 'source_span_ids'}), group_context)
+        group_id = v3_id(group['evidence_group_id'], f'{group_context}.evidence_group_id')
+        if group_id in group_ids:
+            raise DatasetV3Error(f'{context} contains duplicate evidence_group_id {group_id}')
+        group_ids.add(group_id)
+        v3_text(group['description'], f'{group_context}.description')
+        requirement = v3_enum(group['requirement'], REQUIREMENTS, f'{group_context}.requirement')
+        required_count += int(requirement == 'required')
+        if v3_finite(group['weight'], f'{group_context}.weight') <= 0:
+            raise DatasetV3Error(f'{group_context}.weight must be positive')
+        acceptable = set(v3_strings(group['acceptable_candidate_ids'], f'{group_context}.acceptable_candidate_ids', nonempty=True, identifiers=True))
+        spans = set(v3_strings(group['source_span_ids'], f'{group_context}.source_span_ids', nonempty=True, identifiers=True))
+        if not acceptable <= candidate_ids or not spans <= source_span_ids:
+            raise DatasetV3Error(f'{group_context} references unknown candidate or source span')
+        for candidate_id in acceptable:
+            if group_id not in candidate_group_links[candidate_id]:
+                raise DatasetV3Error(f'{group_context} lacks reciprocal candidate evidence link')
+            if not spans & candidate_span_links[candidate_id]:
+                raise DatasetV3Error(f'{group_context} candidate lacks a supporting source span')
+    linked_groups = set().union(*candidate_group_links.values()) if candidate_group_links else set()
+    if linked_groups != group_ids:
+        raise DatasetV3Error(f'{context} candidate/group evidence links are not reciprocal')
+    return (required_count, group_ids)
+
+def v3_validate_task(raw: object, index: int) -> tuple[TaskIdentity, dict[str, tuple[str, ...]]]:
+    context = f'tasks[{index}]'
+    task = v3_object(raw, context)
+    v3_exact(task, frozenset({'task_id', 'customer_id', 'query_id', 'cluster_id', 'partition', 'query', 'conversation_context', 'should_call_rag', 'answerability', 'expected_behavior', 'evaluation_time', 'query_categories', 'business_severity', 'versions', 'leakage_keys', 'source_spans', 'candidates', 'evidence_groups'}), context)
+    task_id = v3_id(task['task_id'], f'{context}.task_id')
+    customer_id = v3_id(task['customer_id'], f'{context}.customer_id')
+    v3_id(task['query_id'], f'{context}.query_id')
+    cluster_id = v3_id(task['cluster_id'], f'{context}.cluster_id')
+    partition = cast('Partition', v3_enum(task['partition'], PARTITIONS, f'{context}.partition'))
+    v3_text(task['query'], f'{context}.query')
+    v3_validate_context(task['conversation_context'], f'{context}.conversation_context')
+    should_call = v3_boolean(task['should_call_rag'], f'{context}.should_call_rag')
+    answerability = v3_enum(task['answerability'], ANSWERABILITY, f'{context}.answerability')
+    behavior = v3_enum(task['expected_behavior'], EXPECTED_BEHAVIORS, f'{context}.expected_behavior')
+    if answerability == 'answerable' and (not should_call or behavior != 'answer'):
+        raise DatasetV3Error(f'{context} answerable tasks must call RAG and answer')
+    if answerability == 'unsupported' and should_call != (behavior == 'abstain'):
+        raise DatasetV3Error(f'{context} unsupported tasks must abstain after RAG or use no_rag without a call')
+    if answerability == 'unsupported' and behavior not in {'abstain', 'no_rag'}:
+        raise DatasetV3Error(f'{context} unsupported task behavior is inconsistent')
+    v3_timestamp(task['evaluation_time'], f'{context}.evaluation_time')
+    v3_strings(task['query_categories'], f'{context}.query_categories', nonempty=True, identifiers=True)
+    v3_enum(task['business_severity'], SEVERITIES, f'{context}.business_severity')
+    v3_validate_versions(task['versions'], f'{context}.versions')
+    leakage_keys = v3_validate_leakage_keys(task['leakage_keys'], f'{context}.leakage_keys')
+    source_span_ids = v3_validate_source_spans(task['source_spans'], f'{context}.source_spans', leakage_keys)
+    candidate_ids, group_links, span_links, qrels = v3_validate_candidates(task['candidates'], f'{context}.candidates', source_span_ids)
+    required_count, group_ids = v3_validate_evidence_groups(task['evidence_groups'], f'{context}.evidence_groups', candidate_ids, source_span_ids, group_links, span_links)
+    if answerability == 'answerable' and (required_count == 0 or not group_ids):
+        raise DatasetV3Error(f'{context} answerable task needs required evidence')
+    if answerability == 'unsupported' and (group_ids or any((qrel not in {0, None} for qrel in qrels))):
+        raise DatasetV3Error(f'{context} unsupported task cannot claim relevant evidence')
+    return (TaskIdentity(task_id, customer_id, partition, cluster_id), leakage_keys)
+
+def v3_validate_no_leakage(identities: tuple[TaskIdentity, ...], task_keys: tuple[dict[str, tuple[str, ...]], ...]) -> None:
+    owners: dict[tuple[str, str], Partition] = {}
+    for identity, leakage_keys in zip(identities, task_keys, strict=True):
+        dimensions = {'cluster': (identity.cluster_id,), **leakage_keys}
+        for dimension, keys in dimensions.items():
+            for key in keys:
+                owner_key = (dimension, key)
+                previous = owners.get(owner_key)
+                if previous is not None and previous != identity.partition:
+                    raise DatasetV3Error(f"cross-partition leakage for {dimension} '{key}': {previous} vs {identity.partition}")
+                owners[owner_key] = identity.partition
+
+def _validate_dataset_v3_fields(raw: object):
+    """Validate a complete dataset and reject every discoverable truth or split ambiguity."""
+    root = v3_object(raw, 'dataset')
+    v3_exact(root, frozenset({'schema_version', 'dataset_id', 'version', 'default_relevance_threshold', 'tasks'}), 'dataset')
+    if v3_text(root['schema_version'], 'dataset.schema_version') != DATASET_V3_SCHEMA_VERSION:
+        raise DatasetV3Error(f'dataset.schema_version must be {DATASET_V3_SCHEMA_VERSION}')
+    dataset_id = v3_id(root['dataset_id'], 'dataset.dataset_id')
+    version = v3_text(root['version'], 'dataset.version')
+    threshold = v3_integer(root['default_relevance_threshold'], 'dataset.default_relevance_threshold', minimum=1)
+    if threshold > 3:
+        raise DatasetV3Error('dataset.default_relevance_threshold must be from 1 through 3')
+    tasks_raw = v3_array(root['tasks'], 'dataset.tasks', nonempty=True)
+    validated = tuple((v3_validate_task(task, index) for index, task in enumerate(tasks_raw)))
+    identities = tuple((item[0] for item in validated))
+    if len({identity.task_id for identity in identities}) != len(identities):
+        raise DatasetV3Error('dataset.tasks must have unique task_id values')
+    task_keys = tuple((item[1] for item in validated))
+    v3_validate_no_leakage(identities, task_keys)
+    revisions = {}
+    for task in tasks_raw:
+        for span in task['source_spans']:
+            key = (task['customer_id'], task['versions']['corpus'], span['document_id'])
+            pin = (span['content_sha256'], span['document_revision_family_id'])
+            if key in revisions and revisions[key] != pin:
+                raise DatasetV3Error('document revision/content drift within corpus version')
+            revisions[key] = pin
+    return (json.dumps(v3_clone_json(root), allow_nan=False, ensure_ascii=False, sort_keys=True).encode('utf-8'), dataset_id, version, threshold, identities)
+
+def validate_dataset_v3(raw: object) -> DatasetV3:
+    """Validate complete source truth and freeze its byte snapshot and identities."""
+    return DatasetV3(*_validate_dataset_v3_fields(raw))
+
+def load_dataset_v3(path: Path) -> DatasetV3:
+    """Read and validate a local DatasetV3 file."""
+    try:
+        raw: Any = json.loads(path.read_text(encoding='utf-8'), parse_constant=v3_reject_constant)
+    except (OSError, json.JSONDecodeError) as error:
+        raise DatasetV3Error(f'cannot read DatasetV3: {error}') from error
+    return validate_dataset_v3(raw)
+
+def v3_reject_constant(value: str) -> None:
+    raise DatasetV3Error(f'non-finite JSON constant is forbidden: {value}')
+
+"""Privacy-safe, data-driven registry for multi-customer offline RAG packs."""
+import json
+import re
+from collections.abc import Mapping
+from pathlib import Path, PurePosixPath
+from typing import Any, Literal, cast
+registry_ID = re.compile('[a-z0-9][a-z0-9_-]{0,63}')
+registry_SHA256 = re.compile('[0-9a-f]{64}')
+registry_GIT_SHA = re.compile('[0-9a-f]{40}')
+
+def registry_object(value: object, context: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping) or any((not isinstance(key, str) for key in value)):
+        raise CustomerRegistryError(f'{context} must be an object with string keys')
+    return cast('Mapping[str, object]', value)
+
+def registry_exact(value: Mapping[str, object], fields: frozenset[str], context: str) -> None:
+    missing = sorted(fields - value.keys())
+    extra = sorted(value.keys() - fields)
+    if missing or extra:
+        raise CustomerRegistryError(f'{context} keys differ; missing={missing}, extra={extra}')
+
+def registry_text(value: object, context: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise CustomerRegistryError(f'{context} must be non-empty text')
+    return value
+
+def registry_id(value: object, context: str) -> str:
+    result = registry_text(value, context)
+    if registry_ID.fullmatch(result) is None:
+        raise CustomerRegistryError(f'{context} must be a privacy-safe identifier')
+    return result
+
+def registry_digest(value: object, context: str) -> str:
+    result = registry_text(value, context)
+    if registry_SHA256.fullmatch(result) is None:
+        raise CustomerRegistryError(f'{context} must be a lowercase SHA-256 digest')
+    return result
+
+def registry_ids(value: object, context: str) -> tuple[str, ...]:
+    if not isinstance(value, list):
+        raise CustomerRegistryError(f'{context} must be an array')
+    result = tuple((registry_id(item, f'{context}[{index}]') for index, item in enumerate(value)))
+    if tuple(sorted(result)) != result or len(result) != len(set(result)):
+        raise CustomerRegistryError(f'{context} must be sorted and unique')
+    return result
+
+def registry_blockers(value: object, context: str) -> tuple[str, ...]:
+    if not isinstance(value, list):
+        raise CustomerRegistryError(f'{context} must be an array')
+    result = tuple((registry_text(item, f'{context}[{index}]') for index, item in enumerate(value)))
+    if len(result) != len(set(result)):
+        raise CustomerRegistryError(f'{context} must be unique')
+    return result
+
+def registry_clone(value: object) -> dict[str, JsonValue]:
+    try:
+        encoded = json.dumps(value, allow_nan=False, ensure_ascii=False, sort_keys=True)
+        loaded: Any = json.loads(encoded)
+    except (TypeError, ValueError) as error:
+        raise CustomerRegistryError('registry must contain only finite JSON values') from error
+    if not isinstance(loaded, dict):
+        raise CustomerRegistryError('registry must be an object')
+    return cast('dict[str, JsonValue]', loaded)
+
+def registry_validate_pack(raw: object, customer_id: str, context: str) -> tuple[str, str | None, str | None, tuple[str, ...]]:
+    pack = registry_object(raw, context)
+    registry_exact(pack, frozenset({'status', 'path', 'manifest_sha256', 'blockers'}), context)
+    status = registry_text(pack['status'], f'{context}.status')
+    if status not in {'available', 'missing'}:
+        raise CustomerRegistryError(f'{context}.status must be available or missing')
+    blockers = registry_blockers(pack['blockers'], f'{context}.blockers')
+    if status == 'missing':
+        if pack['path'] is not None or pack['manifest_sha256'] is not None or (not blockers):
+            raise CustomerRegistryError(f'{context} missing pack needs blockers and cannot claim path or hash')
+        return (status, None, None, blockers)
+    if blockers:
+        raise CustomerRegistryError(f'{context} available pack cannot retain blockers')
+    path = registry_text(pack['path'], f'{context}.path')
+    pure = PurePosixPath(path)
+    expected = PurePosixPath('customer-packs') / customer_id / 'pack.v1.json'
+    if pure.is_absolute() or '..' in pure.parts or pure != expected:
+        raise CustomerRegistryError(f'{context}.path must equal {expected.as_posix()}')
+    manifest_sha256 = registry_digest(pack['manifest_sha256'], f'{context}.manifest_sha256')
+    return (status, path, manifest_sha256, blockers)
+
+def _validate_customer_registry_fields(raw: object):
+    """Validate registry completeness without importing customer identities into code."""
+    root = registry_object(raw, 'customer registry')
+    registry_exact(root, frozenset({'schema_version', 'source_snapshot', 'supplemental_customer_ids', 'customers'}), 'customer registry')
+    if registry_text(root['schema_version'], 'schema_version') != CUSTOMER_REGISTRY_SCHEMA_VERSION:
+        raise CustomerRegistryError(f'schema_version must be {CUSTOMER_REGISTRY_SCHEMA_VERSION}')
+    snapshot = registry_object(root['source_snapshot'], 'source_snapshot')
+    registry_exact(snapshot, frozenset({'repository', 'revision', 'content_sha256', 'observed_at', 'active_customer_ids'}), 'source_snapshot')
+    registry_text(snapshot['repository'], 'source_snapshot.repository')
+    revision = registry_text(snapshot['revision'], 'source_snapshot.revision')
+    if registry_GIT_SHA.fullmatch(revision) is None:
+        raise CustomerRegistryError('source_snapshot.revision must be a full git SHA')
+    registry_digest(snapshot['content_sha256'], 'source_snapshot.content_sha256')
+    registry_text(snapshot['observed_at'], 'source_snapshot.observed_at')
+    active_ids = registry_ids(snapshot['active_customer_ids'], 'source_snapshot.active_customer_ids')
+    supplemental_ids = registry_ids(root['supplemental_customer_ids'], 'supplemental_customer_ids')
+    if set(active_ids) & set(supplemental_ids):
+        raise CustomerRegistryError('source and supplemental customer IDs must not overlap')
+    required_ids = set(active_ids) | set(supplemental_ids)
+    customers_raw = root['customers']
+    if not isinstance(customers_raw, list) or not customers_raw:
+        raise CustomerRegistryError('customers must be a non-empty array')
+    records: list[CustomerRecord] = []
+    seen_ids: set[str] = set()
+    for index, customer_raw in enumerate(customers_raw):
+        context = f'customers[{index}]'
+        customer = registry_object(customer_raw, context)
+        registry_exact(customer, frozenset({'customer_id', 'display_name', 'active', 'source', 'pack'}), context)
+        customer_id = registry_id(customer['customer_id'], f'{context}.customer_id')
+        if customer_id in seen_ids:
+            raise CustomerRegistryError(f'customers contains duplicate {customer_id}')
+        seen_ids.add(customer_id)
+        display_name = registry_text(customer['display_name'], f'{context}.display_name')
+        if customer['active'] is not True:
+            raise CustomerRegistryError(f'{context}.active must be true in the active registry')
+        source = registry_text(customer['source'], f'{context}.source')
+        expected_source = 'registry_snapshot' if customer_id in active_ids else 'supplemental'
+        if source != expected_source:
+            raise CustomerRegistryError(f'{context}.source must be {expected_source}')
+        status, path, manifest_sha256, blockers = registry_validate_pack(customer['pack'], customer_id, f'{context}.pack')
+        records.append(CustomerRecord(customer_id, display_name, cast("Literal['available', 'missing']", status), path, manifest_sha256, blockers))
+    if seen_ids != required_ids:
+        raise CustomerRegistryError(f'customer registry assignment differs; missing={sorted(required_ids - seen_ids)}, unexpected={sorted(seen_ids - required_ids)}')
+    if [record.customer_id for record in records] != sorted(seen_ids):
+        raise CustomerRegistryError('customers must be sorted by customer_id')
+    return (registry_clone(root), tuple(records))
+
+def validate_customer_registry(raw: object) -> CustomerRegistry:
+    """Validate complete customer assignments and retain a detached snapshot."""
+    return CustomerRegistry(*_validate_customer_registry_fields(raw))
+
+def load_customer_registry(path: Path) -> CustomerRegistry:
+    """Read and validate a local privacy-safe registry."""
+    try:
+        raw: Any = json.loads(path.read_text(encoding='utf-8'))
+    except (OSError, json.JSONDecodeError) as error:
+        raise CustomerRegistryError(f'cannot read customer registry: {error}') from error
+    return validate_customer_registry(raw)
+
+"""Content-bound, privacy-safe intake and objective customer-pack readiness."""
+import hashlib
+import json
+import re
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any, Literal, cast
+PACK_SCHEMA_VERSION = 'sable.rag.customer-pack.v1'
+PRIVACY_POLICY_VERSION = 'sable.rag.privacy.v1'
+intake_ID = re.compile('[a-z0-9][a-z0-9._:-]{0,127}')
+intake_SHA256 = re.compile('[0-9a-f]{64}')
+intake_PROHIBITED_KEYS = frozenset({'account_id', 'api_key', 'auth_token', 'call_id', 'cookie', 'credential', 'identity_map', 'org_public_id', 'password', 'private_url', 'raw_screenshot', 'raw_transcript', 'reversible_map', 'screenshot', 'secret', 'session_id', 'transcript', 'user_id'})
+intake_TEXT_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (('email_address', re.compile('\\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\\.[A-Z]{2,}\\b', re.I)), ('direct_platform_identifier', re.compile('\\b(?:acct|account|agt|call|org|session|usr|user)_[A-Za-z0-9]{6,}\\b')), ('credential_value', re.compile('\\b(?:ghp_[A-Za-z0-9]{20,}|github_pat_[A-Za-z0-9_]{20,}|sk-[A-Za-z0-9]{16,})\\b')), ('absolute_url', re.compile('\\b[a-z][a-z0-9+.-]{2,15}://[^\\s\\"\']+', re.I)), ('uuid_identifier', re.compile('\\b[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\\b', re.I)), ('phone_number', re.compile('(?<!\\d)(?:\\+?1[ .-]?)?\\(?\\d{3}\\)?[ .-]\\d{3}[ .-]\\d{4}(?!\\d)')))
+
+class PackIntakeError(ValueError):
+    """Raised when a pack cannot be trusted or content-bound."""
+
+class PackPrivacyError(PackIntakeError):
+    """Raised without echoing prohibited content back into logs."""
+
+    def __init__(self, findings: tuple[PrivacyFinding, ...]) -> None:
+        self.findings = findings
+        summary = ', '.join((f'{item.path}:{item.category}' for item in findings))
+        super().__init__(f'privacy scan rejected pack: {summary}')
+
+def intake_object(value: object, context: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping) or any((not isinstance(key, str) for key in value)):
+        raise PackIntakeError(f'{context} must be an object with string keys')
+    return cast('Mapping[str, object]', value)
+
+def intake_exact(value: Mapping[str, object], fields: frozenset[str], context: str) -> None:
+    missing = sorted(fields - value.keys())
+    extra = sorted(value.keys() - fields)
+    if missing or extra:
+        raise PackIntakeError(f'{context} keys differ; missing={missing}, extra={extra}')
+
+def intake_text(value: object, context: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise PackIntakeError(f'{context} must be non-empty text')
+    return value
+
+def intake_id(value: object, context: str) -> str:
+    result = intake_text(value, context)
+    if intake_ID.fullmatch(result) is None:
+        raise PackIntakeError(f'{context} must be a privacy-safe identifier')
+    return result
+
+def intake_digest(value: object, context: str) -> str:
+    result = intake_text(value, context)
+    if intake_SHA256.fullmatch(result) is None:
+        raise PackIntakeError(f'{context} must be a lowercase SHA-256 digest')
+    return result
+
+def intake_file_sha256(path: Path) -> str:
+    digest = hashlib.sha256()
+    try:
+        with path.open('rb') as source:
+            for chunk in iter(lambda: source.read(1048576), b''):
+                digest.update(chunk)
+    except OSError as error:
+        raise PackIntakeError(f'cannot hash local input {path.name}: {error}') from error
+    return digest.hexdigest()
+
+def intake_redacted_finding(category: str, path: str, value: str) -> PrivacyFinding:
+    return PrivacyFinding(category, path, hashlib.sha256(value.encode('utf-8')).hexdigest())
+
+def scan_privacy(value: object, path: str='$') -> tuple[PrivacyFinding, ...]:
+    """Return deterministic redacted findings without retaining matched sensitive values."""
+    findings: list[PrivacyFinding] = []
+    if isinstance(value, Mapping):
+        for raw_key, item in sorted(value.items(), key=lambda pair: str(pair[0])):
+            key = str(raw_key)
+            child_path = f'{path}.{key}'
+            if key.casefold() in intake_PROHIBITED_KEYS:
+                findings.append(intake_redacted_finding('prohibited_field', child_path, key))
+            findings.extend(scan_privacy(item, child_path))
+    elif isinstance(value, list):
+        for index, item in enumerate(value):
+            findings.extend(scan_privacy(item, f'{path}[{index}]'))
+    elif isinstance(value, str):
+        for category, pattern in intake_TEXT_PATTERNS:
+            for match in pattern.finditer(value):
+                findings.append(intake_redacted_finding(category, path, match.group(0)))
+    return tuple(sorted(findings, key=lambda item: (item.path, item.category, item.value_sha256)))
+
+def intake_approval(raw: object, context: str) -> tuple[bool, str | None]:
+    approval = intake_object(raw, context)
+    intake_exact(approval, frozenset({'status', 'approval_id', 'approved_by', 'approved_at', 'policy_version', 'blocker'}), context)
+    status = intake_text(approval['status'], f'{context}.status')
+    if status not in {'approved', 'pending'}:
+        raise PackIntakeError(f'{context}.status must be approved or pending')
+    if intake_text(approval['policy_version'], f'{context}.policy_version') != PRIVACY_POLICY_VERSION:
+        raise PackIntakeError(f'{context}.policy_version is unsupported')
+    if status == 'approved':
+        intake_id(approval['approval_id'], f'{context}.approval_id')
+        intake_id(approval['approved_by'], f'{context}.approved_by')
+        intake_text(approval['approved_at'], f'{context}.approved_at')
+        if approval['blocker'] is not None:
+            raise PackIntakeError(f'{context} approved state cannot retain a blocker')
+        return (True, None)
+    if any((approval[field] is not None for field in ('approval_id', 'approved_by', 'approved_at'))):
+        raise PackIntakeError(f'{context} pending state cannot claim approval metadata')
+    blocker = intake_text(approval['blocker'], f'{context}.blocker')
+    return (False, blocker)
+
+def intake_validate_pack_manifest(raw: object) -> dict[str, object]:
+    pack = intake_object(raw, 'pack manifest')
+    intake_exact(pack, frozenset({'schema_version', 'pack_id', 'customer_id', 'dataset', 'privacy_approval', 'source_approval', 'holdout', 'expected_level_inputs'}), 'pack manifest')
+    if intake_text(pack['schema_version'], 'schema_version') != PACK_SCHEMA_VERSION:
+        raise PackIntakeError(f'schema_version must be {PACK_SCHEMA_VERSION}')
+    intake_id(pack['pack_id'], 'pack_id')
+    intake_id(pack['customer_id'], 'customer_id')
+    dataset = intake_object(pack['dataset'], 'dataset')
+    intake_exact(dataset, frozenset({'dataset_id', 'version', 'sha256'}), 'dataset')
+    intake_id(dataset['dataset_id'], 'dataset.dataset_id')
+    intake_text(dataset['version'], 'dataset.version')
+    intake_digest(dataset['sha256'], 'dataset.sha256')
+    intake_approval(pack['privacy_approval'], 'privacy_approval')
+    intake_approval(pack['source_approval'], 'source_approval')
+    holdout = intake_object(pack['holdout'], 'holdout')
+    intake_exact(holdout, frozenset({'historical_development_reuse', 'access_log_sha256'}), 'holdout')
+    if not isinstance(holdout['historical_development_reuse'], bool):
+        raise PackIntakeError('holdout.historical_development_reuse must be boolean')
+    if holdout['access_log_sha256'] is not None:
+        intake_digest(holdout['access_log_sha256'], 'holdout.access_log_sha256')
+    inputs = intake_object(pack['expected_level_inputs'], 'expected_level_inputs')
+    intake_exact(inputs, frozenset({'level1', 'level2', 'level3_subject_traces'}), 'expected_level_inputs')
+    for field in ('level1', 'level2', 'level3_subject_traces'):
+        if not isinstance(inputs[field], bool):
+            raise PackIntakeError(f'expected_level_inputs.{field} must be boolean')
+    return dict(pack)
+
+def intake_data_rows(dataset: DatasetV3) -> list[dict[str, Any]]:
+    raw = cast('dict[str, Any]', dataset.value)
+    return cast('list[dict[str, Any]]', raw['tasks'])
+
+def intake_coverage_counts(tasks: list[dict[str, Any]]) -> dict[str, int]:
+    """Count independent clusters represented in each required pilot cohort."""
+    cohorts: dict[str, set[str]] = {'unsupported_cases': set(), 'multi_evidence_cases': set(), 'authority_currentness': set(), 'scope_constraint': set(), 'negation': set(), 'hard_negative_discrimination': set(), 'high_severity': set()}
+    for task in tasks:
+        cluster_id = cast('str', task['cluster_id'])
+        if task['answerability'] == 'unsupported':
+            cohorts['unsupported_cases'].add(cluster_id)
+        if sum((group['requirement'] == 'required' for group in task['evidence_groups'])) >= 2:
+            cohorts['multi_evidence_cases'].add(cluster_id)
+        hard_negative_types = {hard_negative_type for candidate in task['candidates'] for hard_negative_type in candidate['hard_negative_types']}
+        if {'authority_conflict', 'stale'} & hard_negative_types:
+            cohorts['authority_currentness'].add(cluster_id)
+        if 'scope_mismatch' in hard_negative_types:
+            cohorts['scope_constraint'].add(cluster_id)
+        if 'negation_flip' in hard_negative_types or 'negation' in task['query_categories']:
+            cohorts['negation'].add(cluster_id)
+        if hard_negative_types:
+            cohorts['hard_negative_discrimination'].add(cluster_id)
+        if task['business_severity'] in {'high', 'critical'}:
+            cohorts['high_severity'].add(cluster_id)
+    return {name: len(cluster_ids) for name, cluster_ids in cohorts.items()}
+
+def intake_coverage(counts: Mapping[str, int]) -> dict[str, bool]:
+    return {name: count >= (2 if name in {'unsupported_cases', 'multi_evidence_cases'} else 1) for name, count in counts.items()}
+
+def intake_double_labeled(task: dict[str, Any]) -> bool:
+    judged = [candidate for candidate in task['candidates'] if candidate['judgment_status'] == 'judged']
+    return bool(judged) and all((len(candidate['judgments']) >= 2 for candidate in judged))
+
+def assess_readiness(dataset: DatasetV3, pack: Mapping[str, object]) -> ReadinessReport:
+    """Compute predeclared maturity thresholds and named, scoped blockers."""
+    tasks = intake_data_rows(dataset)
+    clusters = {task['cluster_id'] for task in tasks}
+    by_cluster: dict[str, list[dict[str, Any]]] = {}
+    for task in tasks:
+        by_cluster.setdefault(task['cluster_id'], []).append(task)
+    double_labeled_clusters = sum((all((intake_double_labeled(task) for task in cluster_tasks)) for cluster_tasks in by_cluster.values()))
+    double_rate = double_labeled_clusters / len(clusters)
+    coverage_counts = intake_coverage_counts(tasks)
+    coverage = intake_coverage(coverage_counts)
+    blockers: list[ReadinessBlocker] = []
+    privacy_approved, privacy_blocker = intake_approval(pack['privacy_approval'], 'privacy_approval')
+    source_approved, source_blocker = intake_approval(pack['source_approval'], 'source_approval')
+    if not privacy_approved:
+        blockers.append(ReadinessBlocker('privacy_approval_missing', 'data', privacy_blocker or 'pending'))
+    if not source_approved:
+        blockers.append(ReadinessBlocker('source_approval_missing', 'data', source_blocker or 'pending'))
+    if any((candidate['judgment_status'] == 'unknown' for task in tasks for candidate in task['candidates'])):
+        blockers.append(ReadinessBlocker('qrels_incomplete', 'data', 'At least one candidate has an unknown qrel.'))
+    holdout = cast('Mapping[str, object]', pack['holdout'])
+    has_holdout = any((task['partition'] == 'protected_holdout' for task in tasks))
+    if holdout['historical_development_reuse'] is True:
+        blockers.append(ReadinessBlocker('holdout_reused_for_development', 'data', 'Development evidence cannot be promoted as protected holdout truth.'))
+    if has_holdout and holdout['access_log_sha256'] is None:
+        blockers.append(ReadinessBlocker('holdout_access_log_missing', 'data', 'Protected holdout requires a content-bound access log.'))
+    inputs = cast('Mapping[str, object]', pack['expected_level_inputs'])
+    if inputs['level1'] is not True:
+        blockers.append(ReadinessBlocker('level1_input_missing', 'level1', 'Frozen component inputs are missing.'))
+    if inputs['level2'] is not True:
+        blockers.append(ReadinessBlocker('level2_input_missing', 'level2', 'Pipeline inputs are missing.'))
+    if inputs['level3_subject_traces'] is not True:
+        blockers.append(ReadinessBlocker('model_traces_missing', 'level3', 'No valid full-RAG subject traces are available for scoring.'))
+    data_blocked = any((blocker.scope == 'data' for blocker in blockers))
+    pilot_coverage = len(clusters) >= 12 and all(coverage.values())
+    high_severity_double_labeled = all((intake_double_labeled(task) for task in tasks if task['business_severity'] in {'high', 'critical'}))
+    decision_grade = len(clusters) >= 50 and double_rate >= 0.2 and high_severity_double_labeled and pilot_coverage
+    status: Literal['blocked', 'decision_grade', 'draft', 'pilot_ready']
+    if data_blocked:
+        status = 'blocked'
+    elif not pilot_coverage:
+        status = 'draft'
+    elif decision_grade:
+        status = 'decision_grade'
+    else:
+        status = 'pilot_ready'
+    return ReadinessReport(status, len(clusters), double_rate, tuple(blockers), coverage, coverage_counts)
+
+def intake_customer_pack(*, registry_path: Path, pack_root: Path, customer_id: str, dataset_path: Path) -> PackIntake:
+    """Validate one explicitly addressed pack and dataset without copying raw data."""
+    registry: CustomerRegistry = load_customer_registry(registry_path)
+    customer = next((item for item in registry.customers if item.customer_id == customer_id), None)
+    if customer is None:
+        raise PackIntakeError(f'customer {customer_id!r} is not assigned in the registry')
+    if customer.pack_status != 'available' or customer.pack_path is None or customer.pack_manifest_sha256 is None:
+        details = '; '.join(customer.blockers) or 'pack is unavailable'
+        raise PackIntakeError(f'customer pack is blocked: {details}')
+    from ._track_capture import safe_path, _read_file
+    manifest_path = safe_path(pack_root, customer.pack_path)
+    manifest_raw = _read_file(manifest_path, 'sha256:' + customer.pack_manifest_sha256)
+    manifest_findings = scan_privacy(manifest_raw)
+    if manifest_findings:
+        raise PackPrivacyError(manifest_findings)
+    pack = intake_validate_pack_manifest(manifest_raw)
+    if pack['customer_id'] != customer_id:
+        raise PackIntakeError('pack customer_id does not match registry selection')
+    if dataset_path.is_symlink() or not dataset_path.is_file():
+        raise PackIntakeError('dataset path must be an explicit regular local file')
+    dataset_meta = intake_object(pack['dataset'], 'dataset')
+    dataset_bytes = Path(dataset_path).read_bytes()
+    dataset_sha256 = hashlib.sha256(dataset_bytes).hexdigest()
+    if dataset_sha256 != dataset_meta['sha256']:
+        raise PackIntakeError('dataset hash does not match pack manifest')
+    from ._track_capture import strict_json
+    dataset_raw = strict_json(dataset_bytes)
+    findings = scan_privacy(dataset_raw)
+    if findings:
+        raise PackPrivacyError(findings)
+    dataset = validate_dataset_v3(dataset_raw)
+    if dataset.dataset_id != dataset_meta['dataset_id'] or dataset.version != dataset_meta['version']:
+        raise PackIntakeError('dataset identity does not match pack manifest')
+    if any((task.customer_id != customer_id for task in dataset.tasks)):
+        raise PackIntakeError('dataset task customer_id does not match selected customer')
+    readiness = assess_readiness(dataset, pack)
+    return PackIntake(customer_id=customer_id, pack_id=cast('str', pack['pack_id']), manifest_sha256=customer.pack_manifest_sha256, dataset_sha256=dataset_sha256, dataset=dataset, readiness=readiness)
+
+# Sphynx file boundaries use strict JSON and optional external byte commitments.
+def load_dataset_v3(path, *, expected_sha256=None):
+    from ._track_capture import strict_json, byte_digest
+    from .integration_contracts import require_digest
+    path = Path(path)
+    if path.is_symlink() or not path.is_file():
+        raise DatasetV3Error('dataset must be a regular local file')
+    data = path.read_bytes()
+    if expected_sha256 is not None:
+        require_digest(expected_sha256, 'expected_sha256')
+        if byte_digest(data) != expected_sha256:
+            raise DatasetV3Error('dataset source digest mismatch')
+    return validate_dataset_v3(strict_json(data))
+
+
+def load_customer_registry(path):
+    from ._track_capture import strict_json
+    return validate_customer_registry(strict_json(Path(path).read_bytes()))
+
+
+def import_dataset_v3(path, *, expected_sha256, dataset_id, version):
+    """Create an explicitly new V3 release; never rebind an existing per-pack ID."""
+    source = load_dataset_v3(path, expected_sha256=expected_sha256)
+    if dataset_id == source.dataset_id or version == source.version:
+        raise DatasetV3Error('conversion requires a new dataset ID and version')
+    raw = source.value
+    raw.update(dataset_id=dataset_id, version=version)
+    return validate_dataset_v3(raw)
+
+
+def customer_readiness_manifest(registry_path, *, pack_root, dataset_paths=None):
+    """Only verified approved manifests and data can make a registry row ready."""
+    from ._track_capture import byte_digest
+    dataset_paths = dataset_paths or {}
+    registry = load_customer_registry(registry_path)
+    rows = []
+    for customer in registry.customers:
+        row = {'customer_id': customer.customer_id, 'state': 'blocked',
+               'source_digest': None, 'reference_digest': None,
+               'blockers': list(customer.blockers)}
+        if customer.pack_status != 'available':
+            row['blockers'].append('approved_pack_missing')
+        elif customer.customer_id not in dataset_paths:
+            row['blockers'].append('owner_dataset_missing')
+        else:
+            try:
+                intake = intake_customer_pack(registry_path=Path(registry_path), pack_root=Path(pack_root),
+                    customer_id=customer.customer_id, dataset_path=Path(dataset_paths[customer.customer_id]))
+                row['source_digest'] = 'sha256:' + intake.dataset_sha256
+                row['reference_digest'] = row['source_digest']
+                row['blockers'] = [b.code for b in intake.readiness.blockers if b.scope == 'data']
+                if intake.readiness.quality_metrics_allowed:
+                    row['state'] = 'ready'
+                row['maturity'] = intake.readiness.status
+            except (ValueError, OSError) as error:
+                row['blockers'].append(type(error).__name__)
+        rows.append(row)
+    return {'schema_version': 'sphynx.customer-readiness.v1',
+            'registry_digest': byte_digest(Path(registry_path).read_bytes()), 'customers': rows}