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

sphynx/workbench.py

@@ -0,0 +1,378 @@
+"""Pinned native RAG batches with validation and explicit execution.
+
+The canonical batch calls retain the existing coordinator and record formats.
+Native experiment names remain compatible entry points and wire identities.
+"""
+from __future__ import annotations
+import math
+from dataclasses import dataclass, field
+from collections.abc import Mapping
+from types import MappingProxyType
+from typing import Any, cast
+from .components import *
+from .dataset_v3 import DatasetV3, PARTITIONS, Partition, validate_dataset_v3
+JsonValue = Any
+CONTEXT_CONDITIONS = frozenset({'oracle', 'dense', 'a0', 'challenger', 'empty'})
+WORKBENCH_WORKLOAD_SCHEMA_VERSION = 'sable.rag.workbench-workload.v1'
+class WorkbenchError(ValueError):
+    """Raised when a native RAG batch cannot execute or support comparison."""
+
+@dataclass(frozen=True, slots=True)
+class Level3ClaimTruth:
+    """An exact answer phrase and the frozen evidence IDs that support it."""
+    text: str
+    supported_by_evidence_ids: tuple[str, ...] = ()
+
+    @classmethod
+    def from_mapping(cls, raw: object, context: str) -> Level3ClaimTruth:
+        value = _mapping(raw, context)
+        if set(value) != {'text', 'supported_by_evidence_ids'}:
+            raise WorkbenchError(f'{context} keys must be exactly text, supported_by_evidence_ids')
+        return cls(_text(value['text'], f'{context}.text'), _strings(value['supported_by_evidence_ids'], f'{context}.supported_by_evidence_ids'))
+
+    def __post_init__(self) -> None:
+        _text(self.text, 'Level 3 claim text')
+        evidence_ids = _sequence_values(self.supported_by_evidence_ids, 'claim evidence IDs')
+        object.__setattr__(self, 'supported_by_evidence_ids', tuple(_text(item, 'claim evidence ID') for item in evidence_ids))
+        if len(self.supported_by_evidence_ids) != len(set(self.supported_by_evidence_ids)):
+            raise WorkbenchError('Level 3 claim evidence IDs must be unique')
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        return {'text': self.text, 'supported_by_evidence_ids': list(self.supported_by_evidence_ids)}
+
+@dataclass(frozen=True, slots=True)
+class Level3TaskGrading:
+    """Sealed deterministic semantic truth for one full-RAG task."""
+    required_facts: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
+    exact_values: tuple[str, ...] = ()
+    claims: tuple[Level3ClaimTruth, ...] = ()
+
+    def __post_init__(self) -> None:
+        _mapping(self.required_facts, 'Level 3 required facts')
+        _sequence_values(self.exact_values, 'Level 3 exact values')
+        _sequence_values(self.claims, 'Level 3 claims')
+        facts: dict[str, tuple[str, ...]] = {}
+        for raw_fact_id, raw_phrases in self.required_facts.items():
+            fact_id = _text(raw_fact_id, 'Level 3 required fact ID')
+            phrases = tuple((_text(phrase, f'Level 3 required fact {fact_id} phrase') for phrase in _sequence_values(raw_phrases, 'required fact phrases')))
+            if not phrases or len(phrases) != len(set(phrases)):
+                raise WorkbenchError(f'Level 3 required fact {fact_id} needs unique accepted phrases')
+            facts[fact_id] = phrases
+        exact_values = tuple((_text(value, 'Level 3 exact value') for value in self.exact_values))
+        if len(exact_values) != len(set(exact_values)):
+            raise WorkbenchError('Level 3 exact values must be unique')
+        if any((not isinstance(claim, Level3ClaimTruth) for claim in self.claims)):
+            raise WorkbenchError('Level 3 claims must be Level3ClaimTruth values')
+        claim_texts = [claim.text for claim in self.claims]
+        if len(claim_texts) != len(set(claim_texts)):
+            raise WorkbenchError('Level 3 claim texts must be unique')
+        object.__setattr__(self, 'required_facts', MappingProxyType(dict(sorted(facts.items()))))
+        object.__setattr__(self, 'exact_values', exact_values)
+        object.__setattr__(self, 'claims', tuple(self.claims))
+
+    @classmethod
+    def from_mapping(cls, raw: object, context: str) -> Level3TaskGrading:
+        value = _mapping(raw, context)
+        if set(value) != {'required_facts', 'exact_values', 'claims'}:
+            raise WorkbenchError(f'{context} keys must be exactly claims, exact_values, required_facts')
+        raw_facts = _mapping(value['required_facts'], f'{context}.required_facts')
+        facts = {fact_id: _strings(phrases, f'{context}.required_facts.{fact_id}') for fact_id, phrases in raw_facts.items()}
+        raw_claims = value['claims']
+        if not isinstance(raw_claims, list):
+            raise WorkbenchError(f'{context}.claims must be an array')
+        return cls(required_facts=facts, exact_values=_strings(value['exact_values'], f'{context}.exact_values'), claims=tuple((Level3ClaimTruth.from_mapping(claim, f'{context}.claims[{index}]') for index, claim in enumerate(raw_claims))))
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        return {'required_facts': {fact_id: list(phrases) for fact_id, phrases in sorted(self.required_facts.items())}, 'exact_values': list(self.exact_values), 'claims': [claim.to_mapping() for claim in self.claims]}
+
+@dataclass(frozen=True, slots=True)
+class WorkbenchWorkload:
+    """Validated data selection plus optional forced Level 3 contexts."""
+    dataset: DatasetV3
+    customer_ids: tuple[str, ...] = ()
+    partitions: tuple[Partition, ...] = ('development',)
+    level3_context_condition: str = 'dense'
+    level3_contexts: Mapping[str, tuple[str, ...]] = field(default_factory=dict)
+    level3_grading: Mapping[str, Level3TaskGrading] = field(default_factory=dict)
+    _dataset_sha256: str = field(init=False, repr=False)
+    _level3_grading_sha256: str = field(init=False, repr=False)
+
+    def __post_init__(self) -> None:
+        if type(self.dataset) is not DatasetV3:
+            raise WorkbenchError('workload requires a validated DatasetV3')
+        _sequence_values(self.customer_ids, 'customer IDs')
+        _sequence_values(self.partitions, 'partitions')
+        _mapping(self.level3_contexts, 'level3 contexts')
+        _mapping(self.level3_grading, 'level3 grading')
+        _text(self.level3_context_condition, 'level3 context condition')
+        object.__setattr__(self, 'customer_ids', tuple(sorted((_text(customer_id, 'workload customer ID') for customer_id in self.customer_ids))))
+        object.__setattr__(self, 'partitions', tuple(sorted(_text(item, 'partition') for item in self.partitions)))
+        contexts: dict[str, tuple[str, ...]] = {}
+        for raw_task_id, raw_candidate_ids in self.level3_contexts.items():
+            task_id = _text(raw_task_id, 'level3 context task ID')
+            contexts[task_id] = tuple((_text(candidate_id, f'level3 contexts for {task_id}') for candidate_id in _sequence_values(raw_candidate_ids, 'context candidate IDs')))
+        object.__setattr__(self, 'level3_contexts', MappingProxyType(contexts))
+        grading: dict[str, Level3TaskGrading] = {}
+        for raw_task_id, truth in self.level3_grading.items():
+            task_id = _text(raw_task_id, 'Level 3 grading task ID')
+            if not isinstance(truth, Level3TaskGrading):
+                raise WorkbenchError('Level 3 grading values must be Level3TaskGrading values')
+            grading[task_id] = truth
+        object.__setattr__(self, 'level3_grading', MappingProxyType(dict(sorted(grading.items()))))
+        object.__setattr__(self, '_dataset_sha256', json_sha256(self.dataset.value))
+        object.__setattr__(self, '_level3_grading_sha256', json_sha256({task_id: truth.to_mapping() for task_id, truth in sorted(grading.items())}))
+        if self.level3_context_condition not in CONTEXT_CONDITIONS:
+            raise WorkbenchError('Level 3 context condition is invalid')
+        if len(self.customer_ids) != len(set(self.customer_ids)):
+            raise WorkbenchError('workload customer IDs must be unique')
+        if not self.partitions or len(self.partitions) != len(set(self.partitions)):
+            raise WorkbenchError('workload partitions must be non-empty and unique')
+        if not set(self.partitions) <= PARTITIONS:
+            raise WorkbenchError('workload contains an invalid partition')
+        available_partitions = {identity.partition for identity in self.dataset.tasks}
+        missing_partitions = set(self.partitions) - available_partitions
+        if missing_partitions:
+            raise WorkbenchError(f'workload partitions are absent from the dataset: {sorted(missing_partitions)}')
+        known = {identity.customer_id for identity in self.dataset.tasks}
+        unknown = set(self.customer_ids) - known
+        if unknown:
+            raise WorkbenchError(f'workload references unknown customers: {sorted(unknown)}')
+        known_tasks = {identity.task_id for identity in self.dataset.tasks}
+        unknown_tasks = set(self.level3_contexts) - known_tasks
+        if unknown_tasks:
+            raise WorkbenchError(f'Level 3 contexts reference unknown tasks: {sorted(unknown_tasks)}')
+        for task_id, candidate_ids in self.level3_contexts.items():
+            if len(candidate_ids) != len(set(candidate_ids)):
+                raise WorkbenchError(f'Level 3 contexts for {task_id} contain duplicate IDs')
+        unknown_grading_tasks = set(self.level3_grading) - known_tasks
+        if unknown_grading_tasks:
+            raise WorkbenchError(f'Level 3 grading references unknown tasks: {sorted(unknown_grading_tasks)}')
+        raw_tasks = {_text(task.get('task_id'), 'dataset task ID'): task for task in _rows(_mapping(self.dataset.value, 'dataset').get('tasks'), 'dataset.tasks')}
+        for task_id, truth in self.level3_grading.items():
+            known_candidate_ids = {_text(candidate.get('candidate_id'), f'{task_id} candidate ID') for candidate in _rows(raw_tasks[task_id].get('candidates'), 'task.candidates')}
+            cited_ids = {evidence_id for claim in truth.claims for evidence_id in claim.supported_by_evidence_ids}
+            if not cited_ids <= known_candidate_ids:
+                raise WorkbenchError(f'Level 3 grading for {task_id} references unknown evidence IDs: {sorted(cited_ids - known_candidate_ids)}')
+
+    @property
+    def dataset_sha256(self) -> str:
+        return self._dataset_sha256
+
+    @property
+    def level3_grading_sha256(self) -> str:
+        return self._level3_grading_sha256
+
+    @classmethod
+    def from_mapping(cls, dataset: DatasetV3, raw: object) -> WorkbenchWorkload:
+        """Load the strict JSON control document used by CLI or service front ends."""
+        root = _mapping(raw, 'workbench workload')
+        required = {'schema_version', 'dataset', 'customer_ids', 'partitions', 'level3_context_condition', 'level3_contexts'}
+        allowed = required | {'level3_grading'}
+        if not required <= set(root) or not set(root) <= allowed:
+            raise WorkbenchError('workbench workload keys must be exactly the required control fields, with optional level3_grading')
+        if root['schema_version'] != WORKBENCH_WORKLOAD_SCHEMA_VERSION:
+            raise WorkbenchError('workbench workload schema_version is unsupported')
+        dataset_commitment = _mapping(root['dataset'], 'workbench workload.dataset')
+        if set(dataset_commitment) != {'dataset_id', 'version', 'sha256'}:
+            raise WorkbenchError('workbench workload.dataset fields differ')
+        expected_dataset = {'dataset_id': dataset.dataset_id, 'version': dataset.version, 'sha256': json_sha256(dataset.value)}
+        if dict(dataset_commitment) != expected_dataset:
+            raise WorkbenchError('workbench workload does not bind the supplied dataset')
+        contexts_raw = _mapping(root['level3_contexts'], 'level3_contexts')
+        contexts = {task_id: _strings(candidate_ids, f'level3_contexts.{task_id}') for task_id, candidate_ids in contexts_raw.items()}
+        grading_raw = _mapping(root.get('level3_grading', {}), 'level3_grading')
+        grading = {task_id: Level3TaskGrading.from_mapping(truth, f'level3_grading.{task_id}') for task_id, truth in grading_raw.items()}
+        partitions = _strings(root['partitions'], 'partitions')
+        return cls(dataset=dataset, customer_ids=_strings(root['customer_ids'], 'customer_ids'), partitions=cast('tuple[Partition, ...]', partitions), level3_context_condition=_text(root['level3_context_condition'], 'level3_context_condition'), level3_contexts=contexts, level3_grading=grading)
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        result: dict[str, JsonValue] = {'schema_version': WORKBENCH_WORKLOAD_SCHEMA_VERSION, 'dataset': {'dataset_id': self.dataset.dataset_id, 'version': self.dataset.version, 'sha256': self.dataset_sha256}, 'customer_ids': list(self.customer_ids), 'partitions': list(self.partitions), 'level3_context_condition': self.level3_context_condition, 'level3_contexts': {task_id: list(candidate_ids) for task_id, candidate_ids in sorted(self.level3_contexts.items())}}
+        if self.level3_grading:
+            result['level3_grading'] = {task_id: truth.to_mapping() for task_id, truth in sorted(self.level3_grading.items())}
+        return result
+
+def _sequence_values(value, context):
+    if not isinstance(value, (list, tuple)):
+        raise WorkbenchError(f'{context} must be a list or tuple')
+    return tuple(value)
+
+
+def _mapping(value: object, context: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping) or any((not isinstance(key, str) for key in value)):
+        raise WorkbenchError(f'{context} must be an object')
+    return cast('Mapping[str, object]', value)
+
+def _json_value(value: object, context: str) -> JsonValue:
+    """Validate and detach an arbitrary value at the adapter/data boundary."""
+    if value is None or isinstance(value, bool | int | str):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise WorkbenchError(f'{context} contains a non-finite number')
+        return value
+    if isinstance(value, list | tuple):
+        return [_json_value(item, f'{context}[]') for item in value]
+    if isinstance(value, Mapping):
+        result: dict[str, JsonValue] = {}
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise WorkbenchError(f'{context} contains a non-string object key')
+            result[key] = _json_value(item, f'{context}.{key}')
+        return result
+    raise WorkbenchError(f'{context} is not JSON-compatible')
+
+def _rows(value: object, context: str) -> list[Mapping[str, object]]:
+    if not isinstance(value, list):
+        raise WorkbenchError(f'{context} must be an array')
+    return [_mapping(row, f'{context}[{index}]') for index, row in enumerate(value)]
+
+def _strings(value: object, context: str) -> tuple[str, ...]:
+    if not isinstance(value, list):
+        raise WorkbenchError(f'{context} must be an array')
+    return tuple((_text(item, f'{context}[]') for item in value))
+
+def _text(value: object, context: str) -> str:
+    if not isinstance(value, str) or not value:
+        raise WorkbenchError(f'{context} must be non-empty text')
+    return value
+
+def _tasks(workload: WorkbenchWorkload) -> tuple[Mapping[str, object], ...]:
+    if json_sha256(workload.dataset.value) != workload.dataset_sha256:
+        raise WorkbenchError('workload dataset changed after it was frozen')
+    raw = _mapping(workload.dataset.value, 'dataset')
+    selected = set(workload.customer_ids)
+    tasks = tuple((task for task in _rows(raw.get('tasks'), 'dataset.tasks') if (not selected or task.get('customer_id') in selected) and task.get('partition') in workload.partitions))
+    if not tasks:
+        raise WorkbenchError('workload selection contains no tasks')
+    return tasks
+
+from pathlib import Path
+from .integration_contracts import CandidateConfiguration, value_digest
+from .dataset_v3 import load_dataset_v3
+from ._track_capture import strict_json
+
+@dataclass(frozen=True)
+class WorkbenchExecutionPolicy:
+    """Explicit caller permissions and already registered adapters; no dynamic imports."""
+    registry: ComponentRegistry
+    allowed_implementation_kinds: tuple[str, ...] = ('builtin', 'recorded')
+    synthetic: bool = False
+    owner_authorized: bool = False
+    pack_manifest_path: Path | None = None
+    expected_sha256: str | None = None
+    # Downstream tracks may supply an explicit ordinary Python runner.
+    track_runners: Mapping = field(default_factory=dict)
+
+
+def _validated(components, experiment, dataset, workload):
+    if not isinstance(components, ComponentManifest):
+        components=validate_component_manifest(components)
+    else:
+        components=validate_component_manifest(components.value)
+    if isinstance(experiment, ExperimentManifest): experiment=experiment.value
+    experiment=validate_experiment_manifest(experiment,components)
+    if not isinstance(dataset,DatasetV3):
+        dataset=load_dataset_v3(dataset) if isinstance(dataset,(str,Path)) else validate_dataset_v3(dataset)
+    else:
+        dataset=validate_dataset_v3(dataset.value)
+    if isinstance(workload,WorkbenchWorkload): workload=workload.to_mapping()
+    workload=WorkbenchWorkload.from_mapping(dataset,workload)
+    tasks=_tasks(workload)
+    # Source workload validates duplicate IDs; also reject context references outside a case.
+    for task in tasks:
+        supplied=set(workload.level3_contexts.get(task['task_id'],()))
+        known={c['candidate_id'] for c in task['candidates']}
+        if not supplied<=known:
+            raise WorkbenchError('workload context references unknown evidence')
+    return components,experiment,dataset,workload,tasks
+
+
+def validate_experiment(components, experiment, dataset, workload):
+    """Validate frozen controls without constructing, importing or executing adapters."""
+    components,experiment,dataset,workload,tasks=_validated(components,experiment,dataset,workload)
+    selected={r.component_id for cfg in (experiment.baseline,*(a.configuration for a in experiment.alternatives)) for r in cfg.components}
+    external=sorted(c.component_id for c in components.components if c.component_id in selected and c.implementation.kind=='command')
+    return {'valid':True,'dataset_digest':'sha256:'+workload.dataset_sha256,
+            'workload_digest':value_digest(workload.to_mapping()),
+            'component_manifest_digest':'sha256:'+components.sha256,
+            'experiment_digest':'sha256:'+experiment.sha256,
+            'case_ids':[t['task_id'] for t in tasks],
+            'targets':[{'level':t.level,'track':t.track} for t in experiment.targets],
+            'external_components':external,
+            'execution_ready':False,
+            'reason':'Execution needs explicit policy and manifest-bound adapter registrations.'}
+
+
+def run_experiment(components, experiment, dataset, workload, output_dir, *, execution_policy):
+    """Execute the fixed baseline and declared alternatives under explicit permissions."""
+    from .chunking import run_chunking, grade_chunking
+    if not isinstance(execution_policy,WorkbenchExecutionPolicy):
+        raise WorkbenchError('explicit WorkbenchExecutionPolicy is required')
+    if not isinstance(dataset,(str,Path)) or execution_policy.expected_sha256 is None:
+        raise WorkbenchError('execution requires an external pinned dataset path')
+    dataset_path=Path(dataset)
+    data=load_dataset_v3(dataset_path,expected_sha256=execution_policy.expected_sha256)
+    components,experiment,data,workload,tasks=_validated(components,experiment,data,workload)
+    policy=execution_policy
+    if policy.registry.manifest.sha256!=components.sha256:
+        raise WorkbenchError('runtime registry differs from frozen catalog')
+    configurations=(experiment.baseline,*(a.configuration for a in experiment.alternatives))
+    for configuration in configurations:
+        for ref in configuration.components:
+            component=components.by_id[ref.component_id]
+            if component.implementation.kind not in policy.allowed_implementation_kinds:
+                raise WorkbenchError('component execution kind is not authorized')
+            adapter=policy.registry.resolve(ref.component_id,component.capabilities[0],OPERATIONS_BY_KIND[component.kind][0])
+            if adapter.descriptor!=AdapterDescriptor.from_component(component):
+                raise WorkbenchError('registered adapter identity drift')
+    for target in experiment.targets:
+        if target.track!='chunking' and target.track not in policy.track_runners:
+            raise WorkbenchError('target requires an explicit registered track runner: '+target.track)
+    # One native batch boundary; component changes are captured separately.
+    boundary=value_digest({'experiment':experiment.value,'workload':workload.to_mapping()})
+    results=[]
+    for configuration in configurations:
+        for target in experiment.targets:
+            if target.track=='chunking':
+                component=components.by_id[configuration.by_kind['chunker'].component_id]
+                registered=policy.registry.resolve(component.component_id,target,'chunk')
+                candidate=CandidateConfiguration(configuration.configuration_id,'sphynx.chunk.v1',
+                    'sha256:'+component.implementation.artifact_sha256,
+                    {'component_id':component.component_id,'config':component.config,
+                     'workload_digest':value_digest(workload.to_mapping())},'trusted_local')
+                def adapter(request, registered=registered):
+                    output=registered.invoke('chunk',{'documents':[
+                        {'document_id':d['document_id'],'text':d['text']} for d in request['documents']]})
+                    return {'schema_version':'sphynx.chunk.response.v1','case_id':request['case_id'],'chunks':[{key:row[key] for key in ('chunk_id','document_id','start','end','text')} for row in output['chunks']]}
+                run=run_chunking(candidate,adapter,dataset_path,output_dir,
+                    expected_sha256=policy.expected_sha256,synthetic=policy.synthetic,
+                    owner_authorized=policy.owner_authorized,pack_manifest_path=policy.pack_manifest_path,
+                    case_ids=[t['task_id'] for t in tasks],boundary_digest=boundary)
+                evaluation=grade_chunking(run,dataset_path,expected_sha256=policy.expected_sha256)
+                results.append({'configuration_id':configuration.configuration_id,'track':target.track,
+                                'run':run,'evaluation':evaluation})
+            else:
+                result=policy.track_runners[target.track](components=components,configuration=configuration,
+                    registry=policy.registry,dataset_path=dataset_path,workload=workload,
+                    output_dir=output_dir,execution_policy=policy,boundary_digest=boundary)
+                results.append({'configuration_id':configuration.configuration_id,'track':target.track,'result':result})
+    return tuple(results)
+
+
+def validate_batch(components, batch, dataset, workload):
+    """Validate a native RAG batch without executing adapters.
+
+    This is the canonical spelling of ``validate_experiment``. Returned native
+    field names, including ``experiment_digest``, retain their original meaning.
+    """
+    return validate_experiment(components, batch, dataset, workload)
+
+
+def run_batch(components, batch, dataset, workload, output_dir, *, execution_policy):
+    """Run the native baseline and alternatives under the existing policy.
+
+    This call delegates to ``run_experiment``. It does not add common-workflow
+    pipeline substitution, new execution targets, or a new record schema.
+    """
+    return run_experiment(components, batch, dataset, workload, output_dir,
+                          execution_policy=execution_policy)

sphynx/workbench_catalog_data.py

@@ -0,0 +1,13 @@
+"""Metadata-only component candidates; owner data stays external."""
+from .catalog import CandidateDescriptor
+DATASETS = ()  # The eleven blocked customer rows already belong to I-02.
+CANDIDATES = (
+    CandidateDescriptor('workbench.synthetic-chunker.v1', 'rag_chunk', 'sphynx.chunk.v1',
+        'sha256:f38dfca7d06360fe5e024b0d03dd326da7f324ac069de15df4776865e5dcb47d', (), ('trusted_local',), 'available',
+        local_prerequisites=('Explicit synthetic workload and a pinned component manifest.',),
+        supported_python=('>=3.11',)),
+    CandidateDescriptor('workbench.recorded-component.v1', 'rag_workbench', 'sable.rag.component.v1',
+        'sha256:f38dfca7d06360fe5e024b0d03dd326da7f324ac069de15df4776865e5dcb47d', (), ('recorded',), 'available',
+        local_prerequisites=('Complete request-bound recordings and a pinned component manifest.',),
+        supported_python=('>=3.11',)),
+)

sphynx/workbench_tracks.py

@@ -0,0 +1,78 @@
+"""Explicit Level 2/3 runners for the existing declarative workbench.
+
+The seven-component pipeline begins with source documents. The componentized
+Level 3 diagnostic begins with a frozen context and calls router, rewriter and
+generator; it is not an integrated production retriever or opaque system.
+"""
+from .components import AdapterDescriptor
+from .integration_contracts import CandidateConfiguration,value_digest
+from .pipeline import run_pipeline,grade_pipeline,INTERFACE as PIPELINE_INTERFACE
+from .full_rag import run_full_rag,grade_full_rag,INTERFACE as FULL_INTERFACE
+from ._composed_pipeline import compose_pipeline
+from ._componentized_full_rag import compose_full_rag
+from .workbench import WorkbenchError,_tasks
+
+
+def _invoker(components,configuration,registry):
+    def invoke(kind,operation,payload):
+        ref=configuration.by_kind.get(kind)
+        if ref is None:raise WorkbenchError("configuration lacks a required component: "+kind)
+        component=components.by_id[ref.component_id]
+        adapter=registry.resolve(ref.component_id,component.capabilities[0],operation)
+        if adapter.descriptor!=AdapterDescriptor.from_component(component):
+            raise WorkbenchError("registered adapter identity differs from the frozen component")
+        return adapter.invoke(operation,payload)
+    return invoke
+
+
+def _configuration(components,configuration):
+    records={row["component_id"]:row for row in components.value["components"]}
+    return {ref.kind:records[ref.component_id] for ref in configuration.components}
+
+
+def _options(execution_policy,workload,boundary_digest):
+    return {"expected_sha256":execution_policy.expected_sha256,"synthetic":execution_policy.synthetic,
+        "owner_authorized":execution_policy.owner_authorized,"pack_manifest_path":execution_policy.pack_manifest_path,
+        "case_ids":[task["task_id"] for task in _tasks(workload)],"boundary_digest":boundary_digest}
+
+
+def run_workbench_pipeline(*,components,configuration,registry,dataset_path,workload,output_dir,execution_policy,boundary_digest):
+    selected=_configuration(components,configuration)
+    if not {"chunker","embedder","retriever","reranker","fusion","dedup","gate"}<=set(selected):
+        raise WorkbenchError("pipeline requires all seven registered components")
+    invoke=_invoker(components,configuration,registry)
+    gate=components.by_id[configuration.by_kind["gate"].component_id]
+    candidate=CandidateConfiguration(configuration.configuration_id,PIPELINE_INTERFACE,value_digest(selected),
+        {"controlled_config":{"top_k":gate.config.get("top_k",5),"chunking":selected["chunker"],"embedding":selected["embedder"],
+            "retrieval":selected["retriever"],"reranker":selected["reranker"],"fusion":selected["fusion"],
+            "dedup":selected["dedup"],"gating":selected["gate"]}},"trusted_local")
+    run=run_pipeline(candidate,lambda request:compose_pipeline(request,invoke),dataset_path,output_dir,
+        boundary="composed_source_documents",**_options(execution_policy,workload,boundary_digest))
+    evaluation=grade_pipeline(run,dataset_path,expected_sha256=execution_policy.expected_sha256)
+    return {"run":run,"evaluation":evaluation,"boundary":"composed_source_documents"}
+
+
+def run_workbench_full_rag(*,components,configuration,registry,dataset_path,workload,output_dir,execution_policy,boundary_digest):
+    selected=_configuration(components,configuration);invoke=_invoker(components,configuration,registry)
+    subject=components.by_id[configuration.by_kind["full_rag_subject"].component_id]
+    mode=subject.config.get("workbench_execution_mode","opaque")
+    if mode not in ("opaque","componentized"):raise WorkbenchError("full-RAG execution shape differs")
+    if mode=="componentized" and not {"router","rewriter","generator"}<=set(selected):
+        raise WorkbenchError("componentized full-RAG requires router, rewriter and generator")
+    generator=selected["generator"] if mode=="componentized" else selected["full_rag_subject"]
+    candidate=CandidateConfiguration(configuration.configuration_id,FULL_INTERFACE,value_digest(selected),
+        {"generator_digest":value_digest(generator),"prompt_digest":value_digest({"generator_config":generator["config"],"boundary":"fixed-context"}),
+            "components":selected},"trusted_local")
+    if mode=="componentized":adapter=lambda request:compose_full_rag(request,invoke)
+    else:adapter=lambda request:invoke("full_rag_subject","full_rag",request)
+    run=run_full_rag(candidate,adapter,dataset_path,output_dir,execution_shape=mode,
+        context_condition=workload.level3_context_condition,contexts=dict(workload.level3_contexts) or None,
+        **_options(execution_policy,workload,boundary_digest))
+    evaluation=grade_full_rag(run,dataset_path,expected_sha256=execution_policy.expected_sha256)
+    return {"run":run,"evaluation":evaluation,"execution_shape":mode,
+        "semantic_grading":"capture_bound_review_required","predeclared_workload_truth_digest":"sha256:"+workload.level3_grading_sha256}
+
+
+def workbench_track_runners():
+    """Pass explicitly to WorkbenchExecutionPolicy(track_runners=...)."""
+    return {"pipeline":run_workbench_pipeline,"full_rag":run_workbench_full_rag}