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

sphynx/catalog.py

@@ -0,0 +1,272 @@
+"""Content-free discovery contracts and independently owned catalog fragments.
+
+Discovery imports only descriptor fragments, never adapter constructors. Fragment
+modules contain DATASETS and/or CANDIDATES tuples and import no optional model or
+provider dependency. Readiness describes an approved release; caller-local files,
+models, credentials and permission are still checked by execution preflight.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+from importlib import import_module
+from typing import Any
+
+from .contracts import ContractError, _finite_number, _id, _text, _tuple_of_ids
+from .integration_contracts import (
+    CONFIGURATION_SCHEMA, ScoreField, WireValue, _choice, _count,
+    _optional_digest, _schema, _sequence,
+)
+
+DATASET_DESCRIPTOR_SCHEMA = "sphynx.dataset-descriptor.v1"
+CANDIDATE_DESCRIPTOR_SCHEMA = "sphynx.candidate-descriptor.v1"
+# Integration ownership is fixed here so workers add their own data-only module.
+CATALOG_PROVIDER_MODULES = (
+    "sphynx.dataset_catalog_data",       # I-02 dataset release descriptors
+    "sphynx.invocation_catalog_data",    # I-03 routing candidates
+    "sphynx.model_catalog_data",         # I-04 optional/recorded model candidates
+    "sphynx.learned_catalog_data",       # I-05 learned candidates
+    "sphynx.statistical_catalog_data",   # I-06 statistical/guarded candidates
+    "sphynx.retrieval_catalog_data",     # I-07 retrieval candidates
+    "sphynx.workbench_catalog_data",     # I-10/I-11/I-12 via integration owner
+)
+
+
+def _texts(value: Any, field: str) -> tuple[str, ...]:
+    values = _sequence(value, str, field)
+    for item in values:
+        _text(item, field)
+    if len(set(values)) != len(values):
+        raise ContractError(f"{field} must contain unique values")
+    return values
+
+
+@dataclass(frozen=True)
+class DatasetRelationship(WireValue):
+    dataset_id: str
+    kind: str
+    case_count: int | None = None
+    family_digest: str | None = None
+
+    def __post_init__(self) -> None:
+        _id(self.dataset_id, "related dataset_id")
+        _choice(self.kind, ("subset_of", "revised_from", "repeated_question", "shared_family", "shared_source", "supersedes"), "relationship kind")
+        if self.case_count is not None:
+            _count(self.case_count, "relationship case_count")
+        _optional_digest(self.family_digest, "relationship family_digest")
+
+
+@dataclass(frozen=True)
+class DatasetDescriptor(WireValue):
+    dataset_id: str
+    pack_id: str
+    release: str
+    track: str
+    dataset_schema_version: str
+    source_digest: str | None
+    reference_digest: str | None
+    population: str
+    split: str
+    case_count: int | None
+    relevance_threshold: float | None
+    review_status: str
+    state: str
+    reason: str | None = None
+    source_case_count: int | None = None
+    candidate_depth: int | None = None
+    first_stage: str | None = None
+    family_status: str = "unknown"
+    family_digest: str | None = None
+    repeated_question_status: str = "unknown"
+    relationships: tuple[DatasetRelationship, ...] = ()
+    authorization_requirements: tuple[str, ...] = ()
+    local_prerequisites: tuple[str, ...] = ()
+    implementation_status: str = "pending"
+    previously_exercised: bool | None = None
+    superseded_by: tuple[str, ...] = ()
+    schema_version: str = DATASET_DESCRIPTOR_SCHEMA
+
+    def __post_init__(self) -> None:
+        _schema(self.schema_version, DATASET_DESCRIPTOR_SCHEMA)
+        for name in ("dataset_id", "pack_id", "release", "track", "dataset_schema_version", "population", "split", "review_status"):
+            _id(getattr(self, name), name)
+        for name in ("source_digest", "reference_digest", "family_digest"):
+            _optional_digest(getattr(self, name), name)
+        for name in ("case_count", "source_case_count", "candidate_depth"):
+            if getattr(self, name) is not None:
+                _count(getattr(self, name), name, 1 if name == "candidate_depth" else 0)
+        if self.source_case_count is not None and self.case_count is not None and self.source_case_count < self.case_count:
+            raise ContractError("source_case_count must include the selected cohort")
+        if self.relevance_threshold is not None:
+            object.__setattr__(self, "relevance_threshold", _finite_number(self.relevance_threshold, "relevance_threshold"))
+        if self.first_stage is not None:
+            _id(self.first_stage, "first_stage")
+        _choice(self.state, ("ready", "blocked", "superseded"), "dataset state")
+        _choice(self.implementation_status, ("available", "pending", "external_import_required"), "implementation_status")
+        _choice(self.family_status, ("known", "unknown", "not_applicable"), "family_status")
+        _choice(self.repeated_question_status, ("known", "unknown", "not_applicable"), "repeated_question_status")
+        if self.state == "ready" and (self.source_digest is None or self.reference_digest is None or self.implementation_status != "available"):
+            raise ContractError("ready requires exact source/reference identity and an available loader")
+        if self.state != "ready" and self.reason is None:
+            raise ContractError("blocked or superseded datasets require an exact reason")
+        if self.reason is not None:
+            _text(self.reason, "reason")
+        if self.family_status == "known" and self.family_digest is None:
+            raise ContractError("known family relationships require a family digest")
+        relationships = _sequence(self.relationships, DatasetRelationship, "relationships")
+        if any(item.dataset_id == self.dataset_id for item in relationships):
+            raise ContractError("dataset relationships must not reference themselves")
+        keys = [(item.dataset_id, item.kind) for item in relationships]
+        if len(set(keys)) != len(keys):
+            raise ContractError("dataset relationships must be unique")
+        object.__setattr__(self, "relationships", relationships)
+        for name in ("authorization_requirements", "local_prerequisites"):
+            object.__setattr__(self, name, _texts(getattr(self, name), name))
+        object.__setattr__(self, "superseded_by", _tuple_of_ids(self.superseded_by, "superseded_by"))
+        if self.state == "superseded" and not self.superseded_by:
+            raise ContractError("superseded state requires distinct replacement dataset IDs")
+        if self.dataset_id in self.superseded_by or (self.state != "superseded" and self.superseded_by):
+            raise ContractError("invalid superseded_by identity")
+        if self.previously_exercised is not None and type(self.previously_exercised) is not bool:
+            raise ContractError("previously_exercised must be boolean or unknown/null")
+
+    @classmethod
+    def from_dict(cls, value):
+        from collections.abc import Mapping
+        checked = cls._checked_fields(value)
+        if isinstance(checked, dict) and "relationships" in checked:
+            checked["relationships"] = tuple(DatasetRelationship.from_dict(item) for item in _sequence(checked["relationships"], Mapping, "relationships"))
+        return super().from_dict(checked)
+
+
+@dataclass(frozen=True)
+class CandidateDescriptor(WireValue):
+    candidate_id: str
+    track: str
+    interface_version: str
+    source_digest: str | None
+    supported_dataset_ids: tuple[str, ...]
+    execution_modes: tuple[str, ...]
+    implementation_status: str
+    reason: str | None = None
+    local_prerequisites: tuple[str, ...] = ()
+    dependencies: tuple[str, ...] = ()
+    score_fields: tuple[ScoreField, ...] = ()
+    model_identity_required: bool = False
+    supported_python: tuple[str, ...] = ()
+    configuration_schema_version: str = CONFIGURATION_SCHEMA
+    schema_version: str = CANDIDATE_DESCRIPTOR_SCHEMA
+
+    def __post_init__(self) -> None:
+        _schema(self.schema_version, CANDIDATE_DESCRIPTOR_SCHEMA)
+        _schema(self.configuration_schema_version, CONFIGURATION_SCHEMA)
+        for name in ("candidate_id", "track", "interface_version"):
+            _id(getattr(self, name), name)
+        _optional_digest(self.source_digest, "source_digest")
+        _choice(self.implementation_status, ("available", "pending", "blocked"), "implementation_status")
+        if self.implementation_status == "available" and self.source_digest is None:
+            raise ContractError("available candidates require a source identity")
+        if self.implementation_status != "available" and self.reason is None:
+            raise ContractError("pending/blocked candidates require a reason")
+        if self.reason is not None:
+            _text(self.reason, "reason")
+        object.__setattr__(self, "supported_dataset_ids", _tuple_of_ids(self.supported_dataset_ids, "supported_dataset_ids"))
+        modes = _texts(self.execution_modes, "execution_modes")
+        if not modes:
+            raise ContractError("execution_modes must be nonempty")
+        for mode in modes:
+            _choice(mode, ("recorded", "trusted_local", "external_command", "live_provider"), "execution mode")
+        object.__setattr__(self, "execution_modes", modes)
+        for name in ("local_prerequisites", "dependencies", "supported_python"):
+            object.__setattr__(self, name, _texts(getattr(self, name), name))
+        scores = _sequence(self.score_fields, ScoreField, "score_fields")
+        if len({item.field_id for item in scores}) != len(scores):
+            raise ContractError("candidate score field identities must be unique")
+        object.__setattr__(self, "score_fields", scores)
+        if type(self.model_identity_required) is not bool:
+            raise ContractError("model_identity_required must be a boolean")
+
+    @classmethod
+    def from_dict(cls, value):
+        from collections.abc import Mapping
+        checked = cls._checked_fields(value)
+        if isinstance(checked, dict) and "score_fields" in checked:
+            checked["score_fields"] = tuple(ScoreField.from_dict(item) for item in _sequence(checked["score_fields"], Mapping, "score_fields"))
+        return super().from_dict(checked)
+
+
+def merge_catalog_descriptors(*groups):
+    """Merge data-only fragments; no ID may overwrite a previous release."""
+    result = []
+    seen = set()
+    for group in groups:
+        if not isinstance(group, (tuple, list)):
+            raise ContractError("catalog fragments must be descriptor sequences")
+        for item in group:
+            if isinstance(item, DatasetDescriptor):
+                key = ("dataset", item.dataset_id)
+            elif isinstance(item, CandidateDescriptor):
+                key = ("candidate", item.candidate_id)
+            else:
+                raise ContractError("catalog fragments must contain validated descriptors")
+            if key in seen:
+                raise ContractError(f"catalog identity {key[1]!r} is duplicated or substitutes a release")
+            seen.add(key)
+            result.append(item)
+    return tuple(result)
+
+
+@dataclass(frozen=True)
+class Catalog:
+    datasets: tuple[DatasetDescriptor, ...] = ()
+    candidates: tuple[CandidateDescriptor, ...] = ()
+
+    def __post_init__(self) -> None:
+        datasets = _sequence(self.datasets, DatasetDescriptor, "datasets")
+        candidates = _sequence(self.candidates, CandidateDescriptor, "candidates")
+        merge_catalog_descriptors(datasets, candidates)
+        object.__setattr__(self, "datasets", datasets)
+        object.__setattr__(self, "candidates", candidates)
+
+    def list_datasets(self, track: str | None = None) -> tuple[DatasetDescriptor, ...]:
+        return tuple(item for item in self.datasets if track is None or item.track == track)
+
+    def get_dataset(self, dataset_id: str) -> DatasetDescriptor:
+        _id(dataset_id, "dataset_id")
+        for item in self.datasets:
+            if item.dataset_id == dataset_id:
+                return item
+        raise ValueError(f"Unknown dataset {dataset_id!r}; call list_datasets() for installed release IDs")
+
+    def list_candidates(self, track: str | None = None) -> tuple[CandidateDescriptor, ...]:
+        return tuple(item for item in self.candidates if track is None or item.track == track)
+
+
+def _installed_catalog() -> Catalog:
+    groups = []
+    for name in CATALOG_PROVIDER_MODULES:
+        try:
+            module = import_module(name)
+        except ModuleNotFoundError as exc:
+            if exc.name != name:
+                raise  # An installed provider with a missing dependency must fail visibly.
+            continue
+        groups.append(getattr(module, "DATASETS", ()))
+        groups.append(getattr(module, "CANDIDATES", ()))
+    descriptors = merge_catalog_descriptors(*groups)
+    return Catalog(
+        tuple(item for item in descriptors if isinstance(item, DatasetDescriptor)),
+        tuple(item for item in descriptors if isinstance(item, CandidateDescriptor)),
+    )
+
+
+def list_datasets(track: str | None = None) -> tuple[DatasetDescriptor, ...]:
+    """List installed content-free releases, without data/model/provider execution."""
+    return _installed_catalog().list_datasets(track)
+
+
+def get_dataset(dataset_id: str) -> DatasetDescriptor:
+    return _installed_catalog().get_dataset(dataset_id)
+
+
+def list_candidates(track: str | None = None) -> tuple[CandidateDescriptor, ...]:
+    return _installed_catalog().list_candidates(track)

sphynx/chunking.py

@@ -0,0 +1,372 @@
+"""Sphynx-owned port of the source contracts; no sibling runtime dependency."""
+from __future__ import annotations
+from typing import Any
+JsonValue = Any
+
+import hashlib, math, re
+from dataclasses import dataclass
+from collections.abc import Mapping, Sequence
+from typing import cast
+DEPTHS = (5, 10, 15, 30)
+class Level1Error(ValueError):
+    """Raised when a Level 1 evaluation is not causally comparable."""
+
+@dataclass(frozen=True, slots=True)
+class Chunk:
+    chunk_id: str
+    document_id: str
+    start: int
+    end: int
+    text: str
+
+def _percentile(values: Sequence[float], fraction: float) -> float | None:
+    if not values:
+        return None
+    ordered = sorted(values)
+    position = (len(ordered) - 1) * fraction
+    lower = math.floor(position)
+    upper = math.ceil(position)
+    if lower == upper:
+        return ordered[lower]
+    return ordered[lower] + (ordered[upper] - ordered[lower]) * (position - lower)
+
+def _distribution(values: Sequence[float]) -> dict[str, float | int | None]:
+    return {'count': len(values), 'min': min(values) if values else None, 'mean': sum(values) / len(values) if values else None, 'p50': _percentile(values, 0.5), 'p95': _percentile(values, 0.95), 'max': max(values) if values else None}
+
+def _token_spans(text: str) -> tuple[tuple[int, int], ...]:
+    return tuple(((match.start(), match.end()) for match in re.finditer('\\S+', text)))
+
+def evaluate_chunking(documents: Mapping[str, str], source_spans: Sequence[Mapping[str, object]], evidence_groups: Sequence[Mapping[str, object]], chunks: Sequence[Chunk], *, expected_document_sha256: Mapping[str, str]) -> dict[str, JsonValue]:
+    """Score a versioned chunk set against immutable source spans."""
+    for document_id, content in documents.items():
+        digest = hashlib.sha256(content.encode()).hexdigest()
+        if expected_document_sha256.get(document_id) != digest:
+            raise Level1Error(f'document {document_id} does not match its immutable hash')
+    by_document: dict[str, list[Chunk]] = {document_id: [] for document_id in documents}
+    for chunk in chunks:
+        document_content = documents.get(chunk.document_id)
+        if document_content is None or chunk.start < 0 or chunk.end <= chunk.start or (chunk.end > len(document_content)):
+            raise Level1Error(f'chunk {chunk.chunk_id} has invalid document bounds')
+        if chunk.text != document_content[chunk.start:chunk.end]:
+            raise Level1Error(f'chunk {chunk.chunk_id} text does not bind its source document')
+        by_document[chunk.document_id].append(chunk)
+    contained = 0
+    intersections: list[int] = []
+    gold_token_total = 0
+    covered_gold_tokens = 0
+    emitted_token_total = 0
+    relevant_emitted_tokens = 0
+    duplicate_positions = 0
+    relevant_chunk_ids: set[str] = set()
+    span_to_chunks: dict[str, set[str]] = {}
+    for span in source_spans:
+        document_id = cast('str', span['document_id'])
+        start, end = (cast('int', span['start']), cast('int', span['end']))
+        span_id = cast('str', span['source_span_id'])
+        overlapping = {chunk.chunk_id for chunk in by_document.get(document_id, []) if max(start, chunk.start) < min(end, chunk.end)}
+        intersections.append(len(overlapping))
+        span_to_chunks[span_id] = overlapping
+        relevant_chunk_ids.update(overlapping)
+        contained += int(any((chunk.start <= start and chunk.end >= end for chunk in by_document.get(document_id, []))))
+        tokens = _token_spans(documents[document_id])
+        gold_positions = {(token_start, token_end) for token_start, token_end in tokens if token_start < end and token_end > start}
+        gold_token_total += len(gold_positions)
+        coverage: dict[tuple[int, int], int] = {position: 0 for position in gold_positions}
+        for chunk in by_document.get(document_id, []):
+            for position in gold_positions:
+                if position[0] < chunk.end and position[1] > chunk.start:
+                    coverage[position] += 1
+        covered_gold_tokens += sum((count > 0 for count in coverage.values()))
+    for document_id, document_chunks in by_document.items():
+        positions: dict[tuple[int, int], int] = {}
+        relevant_ranges = [(cast('int', span['start']), cast('int', span['end'])) for span in source_spans if span['document_id'] == document_id]
+        for chunk in document_chunks:
+            for position in _token_spans(documents[document_id]):
+                if position[0] < chunk.end and position[1] > chunk.start:
+                    emitted_token_total += 1
+                    positions[position] = positions.get(position, 0) + 1
+                    relevant_emitted_tokens += int(any((position[0] < end and position[1] > start for start, end in relevant_ranges)))
+        duplicate_positions += sum((max(count - 1, 0) for count in positions.values()))
+    required_groups = [group for group in evidence_groups if group['requirement'] == 'required']
+    oracle_order = sorted(chunks, key=lambda chunk: (-sum((len(span_to_chunks.get(cast('str', span_id), set()) & {chunk.chunk_id}) * cast('float', group['weight']) for group in evidence_groups for span_id in cast('list[object]', group['source_span_ids']))), chunk.chunk_id))
+    group_recall: dict[str, float | None] = {}
+    for depth in DEPTHS:
+        selected = {chunk.chunk_id for chunk in oracle_order[:depth]}
+        covered = sum((any((selected & span_to_chunks.get(cast('str', span_id), set()) for span_id in cast('list[object]', group['source_span_ids']))) for group in required_groups))
+        group_recall[str(depth)] = None if not required_groups else covered / len(required_groups)
+    chunk_chars = [float(chunk.end - chunk.start) for chunk in chunks]
+    chunk_tokens = [float(len(_token_spans(chunk.text))) for chunk in chunks]
+    return cast('dict[str, JsonValue]', {'evidence_span_containment': None if not source_spans else contained / len(source_spans), 'boundary_fragmentation': _distribution([float(value) for value in intersections]), 'gold_token_precision': None if emitted_token_total == 0 else relevant_emitted_tokens / emitted_token_total, 'gold_token_recall': None if gold_token_total == 0 else covered_gold_tokens / gold_token_total, 'evidence_density': None if not chunks else len(relevant_chunk_ids) / len(chunks), 'duplicate_token_rate': None if emitted_token_total == 0 else duplicate_positions / emitted_token_total, 'chunk_character_distribution': _distribution(chunk_chars), 'chunk_token_distribution': _distribution(chunk_tokens), 'oracle_evidence_group_recall': group_recall})
+
+# Standalone Sphynx execution surface. Only captured responses enter grading.
+from dataclasses import asdict, replace
+from time import perf_counter
+from .contracts import ContractError
+from .integration_contracts import CandidateConfiguration, ComparisonIdentity, TrackCaseCapture, value_digest, require_comparable
+from .dataset_v3 import load_dataset_v3, assess_readiness, intake_validate_pack_manifest, scan_privacy
+from ._track_capture import (create_run, write_artifact, finish_run, read_artifact, verify_track_run,
+    write_evaluation, verify_track_evaluation, open_track_run, open_track_evaluation, byte_digest, strict_json)
+from .packs import PackDescriptor, ExecutionPolicy
+from pathlib import Path
+
+PACK = PackDescriptor('rag.chunk.v1', 'v1', 'Source-bound chunking evaluation', 'rag_chunk',
+    'sphynx.chunk.v1', 'sable.rag.dataset.v3', 'sphynx.chunk.request.v1', 'sphynx.chunk.response.v1',
+    'runnable', 'Span and token recovery on frozen source documents.',
+    ExecutionPolicy('sphynx.chunk.policy.v1', 1, 30.0, 'trusted-local'),
+    metric_release='sphynx.chunk.metrics.v1', required_inputs=('Pinned DatasetV3',), run_api='run_chunking')
+
+_source_evaluate_chunking = evaluate_chunking
+
+def evaluate_chunking(documents, source_spans, evidence_groups, chunks, *, expected_document_sha256):
+    """Source-parity metrics with strict span, revision and chunk identity validation."""
+    if set(documents) != set(expected_document_sha256):
+        raise Level1Error('document hash inventory differs')
+    ids = [chunk.chunk_id for chunk in chunks]
+    if len(ids) != len(set(ids)) or any(not isinstance(i, str) or not i for i in ids):
+        raise Level1Error('chunk IDs must be unique nonempty strings')
+    for chunk in chunks:
+        if type(chunk.start) is not int or type(chunk.end) is not int:
+            raise Level1Error('chunk bounds must be integers')
+    span_ids = set()
+    for span in source_spans:
+        sid, did = span['source_span_id'], span['document_id']
+        if sid in span_ids or did not in documents:
+            raise Level1Error('duplicate span or unknown document')
+        span_ids.add(sid)
+        start, end = span['start'], span['end']
+        if type(start) is not int or type(end) is not int or not 0 <= start < end <= len(documents[did]):
+            raise Level1Error('invalid source span bounds')
+        if span.get('content', documents[did]) != documents[did] or span.get('exact_text', documents[did][start:end]) != documents[did][start:end]:
+            raise Level1Error('source span content/revision drift')
+    group_ids = set()
+    for group in evidence_groups:
+        gid = group['evidence_group_id']
+        if gid in group_ids or not set(group['source_span_ids']) <= span_ids:
+            raise Level1Error('duplicate group or unknown source reference')
+        group_ids.add(gid)
+        if group['requirement'] not in ('required','optional') or type(group['weight']) not in (int,float) or not math.isfinite(group['weight']) or group['weight'] <= 0:
+            raise Level1Error('invalid evidence group')
+    return _source_evaluate_chunking(documents, source_spans, evidence_groups, chunks,
+                                     expected_document_sha256=expected_document_sha256)
+
+
+def _documents(task):
+    docs = {}
+    for span in task['source_spans']:
+        doc = {'document_id': span['document_id'], 'text': span['content'],
+               'content_sha256': span['content_sha256'],
+               'document_revision_family_id': span['document_revision_family_id']}
+        if doc['document_id'] in docs and docs[doc['document_id']] != doc:
+            raise ContractError('document revision drift')
+        docs[doc['document_id']] = doc
+    return list(docs.values())
+
+
+def _request(task, policy):
+    return {'schema_version': 'sphynx.chunk.request.v1', 'case_id': task['task_id'],
+            'documents': _documents(task), 'policy': policy}
+
+
+def _parse_response(response, task):
+    if not isinstance(response, dict) or set(response) != {'schema_version','case_id','chunks'}:
+        raise ContractError('chunk response fields differ')
+    if response['schema_version'] != 'sphynx.chunk.response.v1' or response['case_id'] != task['task_id']:
+        raise ContractError('chunk response identity differs')
+    if not isinstance(response['chunks'], list):
+        raise ContractError('chunks must be an array')
+    chunks = []
+    for row in response['chunks']:
+        if not isinstance(row, dict) or set(row) != {'chunk_id','document_id','start','end','text'}:
+            raise ContractError('chunk fields differ')
+        chunks.append(Chunk(**row))
+    documents = {d['document_id']: d['text'] for d in _documents(task)}
+    hashes = {d['document_id']: d['content_sha256'] for d in _documents(task)}
+    return evaluate_chunking(documents, task['source_spans'], task['evidence_groups'], chunks,
+                             expected_document_sha256=hashes)
+
+
+def _policy(dataset, *, synthetic, owner_authorized, pack_manifest_path, trials, attempts, boundary_digest):
+    for count in (trials, attempts):
+        if type(count) is not int or count < 1:
+            raise ContractError('trials and attempts must be positive integers')
+    if type(synthetic) is not bool:
+        raise ContractError('synthetic must be explicit boolean')
+    approval = None
+    if not synthetic:
+        if owner_authorized is not True or pack_manifest_path is None:
+            raise ContractError('owner authorization and an approved pack manifest are required')
+        data = Path(pack_manifest_path).read_bytes()
+        pack = intake_validate_pack_manifest(strict_json(data))
+        if pack['dataset'] != {'dataset_id': dataset.dataset_id, 'version': dataset.version,
+                               'sha256': dataset._source_digest.removeprefix('sha256:')}:
+            raise ContractError('approved pack does not bind dataset bytes')
+        if any(t.customer_id != pack['customer_id'] for t in dataset.tasks):
+            raise ContractError('pack customer identity differs')
+        if scan_privacy(dataset.value):
+            raise ContractError('pack privacy scan failed')
+        if not assess_readiness(dataset, pack).quality_metrics_allowed:
+            raise ContractError('approved dataset remains blocked for quality claims')
+        approval = byte_digest(data)
+    return {'version':'sphynx.chunk.policy.v1', 'synthetic':synthetic,
+            'approved_manifest_digest':approval, 'trials':trials, 'attempts':attempts,
+            'selection':'first_success_per_trial', 'boundary_digest':boundary_digest}
+
+
+def _identity(dataset, source_digest, tasks, policy):
+    return ComparisonIdentity('rag_chunk', PACK.pack_id, PACK.pack_release, 'sable.rag.dataset.v3',
+        source_digest, value_digest([t['task_id'] for t in tasks]),
+        value_digest([{'source_spans': t['source_spans'], 'evidence_groups': t['evidence_groups']} for t in tasks]),
+        value_digest(policy), PACK.metric_release, 'sphynx.chunk.grader.v1',
+        policy['boundary_digest'] or value_digest({'boundary':'chunker', 'dataset':source_digest}))
+
+
+def run_chunking(candidate, adapter, dataset_path, output_dir, *, expected_sha256, synthetic=False,
+                 owner_authorized=False, pack_manifest_path=None, trials=1, attempts=1,
+                 case_ids=None, boundary_digest=None):
+    dataset = load_dataset_v3(dataset_path, expected_sha256=expected_sha256)
+    # A separate byte commitment is supplied to approval checks; no data identity is rewritten.
+    policy = _policy_for_source(dataset, expected_sha256, synthetic=synthetic,
+        owner_authorized=owner_authorized, pack_manifest_path=pack_manifest_path,
+        trials=trials, attempts=attempts, boundary_digest=boundary_digest)
+    tasks = _select_tasks(dataset, case_ids)
+    if not isinstance(candidate, CandidateConfiguration) or candidate.interface_version != PACK.interface_version:
+        raise ContractError('candidate must declare the chunk interface')
+    if candidate.execution_mode not in ('trusted_local', 'recorded'):
+        raise ContractError('chunk runner requires an explicit trusted local or recorded adapter')
+    if candidate.execution_mode == 'recorded':
+        if not isinstance(adapter, Mapping) or candidate.parameters.get('recordings_digest') != value_digest(adapter):
+            raise ContractError('recorded outputs need their complete pinned recording digest')
+        adapter = strict_json(__import__('json').dumps(dict(adapter),allow_nan=False))
+    elif not callable(adapter):
+        raise ContractError('trusted local adapter must be callable')
+    approval_source = None if synthetic else Path(pack_manifest_path).read_bytes().decode('utf-8')
+    observed = {'approved_manifest_source':approval_source}
+    _verify_approval(dataset, expected_sha256, policy, observed)
+    identity = _identity(dataset, expected_sha256, tasks, policy)
+    ordered = [t['task_id'] for t in tasks]
+    path = create_run(output_dir, identity, candidate, ordered)
+    captures=[]
+    for index, task in enumerate(tasks):
+        for trial in range(1,trials+1):
+            for attempt in range(1,attempts+1):
+                request = _request(task, policy)
+                prefix = f'cases/{index}/{trial}/{attempt}/'
+                request_binding = write_artifact(path,prefix+'request.json',request)
+                response_binding = None
+                failure=None
+                begin=perf_counter()
+                try:
+                    response = adapter[value_digest(request)] if candidate.execution_mode == 'recorded' else adapter(strict_json(__import__('json').dumps(request)))
+                    response_binding = write_artifact(path,prefix+'response.json',response)
+                    _parse_response(response,task)
+                except Exception:
+                    failure='invalid_response' if response_binding is not None else 'candidate_failure'
+                observed_binding=write_artifact(path,prefix+'observed.json',observed)
+                captures.append(TrackCaseCapture(task['task_id'],trial,attempt,request_binding,response_binding,observed_binding,failure,
+                                                 (perf_counter()-begin)*1000))
+    return finish_run(path,identity,candidate,ordered,captures)
+
+
+def _policy_for_source(dataset, source_digest, **kwargs):
+    # Pass immutable dataset and raw-file commitment together without altering DatasetV3.
+    class BoundDataset:
+        _source_digest=source_digest
+        dataset_id=dataset.dataset_id
+        version=dataset.version
+        tasks=dataset.tasks
+        value=dataset.value
+    return _policy(BoundDataset(), **kwargs)
+
+
+def _select_tasks(dataset, case_ids):
+    tasks=dataset.value['tasks']
+    if case_ids is None: return tasks
+    case_ids=tuple(case_ids)
+    known={t['task_id']:t for t in tasks}
+    if not case_ids or len(set(case_ids))!=len(case_ids) or not set(case_ids)<=set(known):
+        raise ContractError('invalid selected case identities')
+    return [known[c] for c in case_ids]
+
+
+def grade_chunking(run, dataset_path, *, expected_sha256):
+    dataset=load_dataset_v3(dataset_path,expected_sha256=expected_sha256)
+    manifest=verify_track_run(run)
+    tasks=_select_tasks(dataset,manifest.case_ids)
+    policy=read_artifact(run.path,manifest.captures[0].request).get('policy')
+    if not isinstance(policy,dict) or set(policy)!={'version','synthetic','approved_manifest_digest','trials','attempts','selection','boundary_digest'}:
+        raise ContractError('capture policy fields differ')
+    if policy['version']!='sphynx.chunk.policy.v1' or policy['selection']!='first_success_per_trial' or type(policy['synthetic']) is not bool:
+        raise ContractError('unsupported capture policy')
+    require_comparable(_identity(dataset,expected_sha256,tasks,policy),manifest.identity)
+    manifest=verify_track_run(run,expected_case_ids=[t['task_id'] for t in tasks],
+        expected_requests={t['task_id']:_request(t,policy) for t in tasks},trials=policy['trials'],attempts=policy['attempts'])
+    for capture in manifest.captures:
+        if capture.observed is None:
+            raise ContractError('capture lacks its approval observation')
+        _verify_approval(dataset,expected_sha256,policy,read_artifact(run.path,capture.observed))
+    results=[]
+    for task in tasks:
+        for trial in range(1,policy['trials']+1):
+            selected=None
+            for capture in sorted(manifest.captures,key=lambda c:c.attempt_index):
+                if capture.case_id!=task['task_id'] or capture.trial_index!=trial: continue
+                if capture.failure is None and capture.response is not None:
+                    score=_parse_response(read_artifact(run.path,capture.response),task)
+                    if selected is None: selected=score
+            results.append({'case_id':task['task_id'],'trial_index':trial,'metrics':selected})
+    good=[r['metrics'] for r in results if r['metrics'] is not None]
+    summary={key: (sum(m[key] for m in good if m[key] is not None)/sum(m[key] is not None for m in good)
+                    if any(m[key] is not None for m in good) else None)
+             for key in ('evidence_span_containment','gold_token_precision','gold_token_recall','evidence_density','duplicate_token_rate')}
+    summary.update(coverage=len(good)/len(results),successful_trials=len(good),expected_trials=len(results))
+    return write_evaluation(run,manifest.identity,{'summary':summary,'cases':results,
+        'quality_scope':'synthetic_fixture' if policy['synthetic'] else 'owner_approved',
+        'complete':len(good)==len(results)})
+
+
+def report_chunking(evaluation, dataset_path, *, expected_sha256):
+    # Revalidate the complete capture/request boundary without invoking any candidate.
+    _verify_evaluation_dataset(evaluation,dataset_path,expected_sha256)
+    return verify_track_evaluation(evaluation).to_dict()
+
+
+def _verify_evaluation_dataset(evaluation, dataset_path, expected_sha256):
+    dataset=load_dataset_v3(dataset_path,expected_sha256=expected_sha256)
+    manifest=verify_track_run(evaluation.run)
+    policy=read_artifact(evaluation.run.path,manifest.captures[0].request)['policy']
+    tasks=_select_tasks(dataset,manifest.case_ids)
+    require_comparable(_identity(dataset,expected_sha256,tasks,policy),manifest.identity)
+    for capture in manifest.captures:
+        if capture.observed is None: raise ContractError('missing approval observation')
+        _verify_approval(dataset,expected_sha256,policy,read_artifact(evaluation.run.path,capture.observed))
+    verify_track_run(evaluation.run,expected_case_ids=[t['task_id'] for t in tasks],
+        expected_requests={t['task_id']:_request(t,policy) for t in tasks},trials=policy['trials'],attempts=policy['attempts'])
+
+
+def compare_chunking(baseline,candidate,dataset_path,*,expected_sha256):
+    left=report_chunking(baseline,dataset_path,expected_sha256=expected_sha256)
+    right=report_chunking(candidate,dataset_path,expected_sha256=expected_sha256)
+    require_comparable(ComparisonIdentity.from_dict(left['identity']),ComparisonIdentity.from_dict(right['identity']))
+    return {'baseline':left['evaluation_id'],'candidate':right['evaluation_id'],
+            'delta':{key: None if value is None or right['metrics']['summary'][key] is None
+                     else right['metrics']['summary'][key]-value
+                     for key,value in left['metrics']['summary'].items()}}
+
+
+def _verify_approval(dataset, source_digest, policy, observed):
+    if not isinstance(observed,dict) or set(observed)!={'approved_manifest_source'}:
+        raise ContractError('approval observation fields differ')
+    source=observed['approved_manifest_source']
+    if policy['synthetic']:
+        if source is not None or policy['approved_manifest_digest'] is not None:
+            raise ContractError('synthetic captures cannot claim owner approval')
+        return
+    if not isinstance(source,str) or byte_digest(source.encode('utf-8'))!=policy['approved_manifest_digest']:
+        raise ContractError('approval evidence digest mismatch')
+    pack=intake_validate_pack_manifest(strict_json(source))
+    if pack['dataset']!={'dataset_id':dataset.dataset_id,'version':dataset.version,'sha256':source_digest.removeprefix('sha256:')}:
+        raise ContractError('approval evidence dataset mismatch')
+    if any(t.customer_id!=pack['customer_id'] for t in dataset.tasks):
+        raise ContractError('approval evidence customer mismatch')
+    if not assess_readiness(dataset,pack).quality_metrics_allowed:
+        raise ContractError('retained approval evidence does not permit quality claims')