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

sphynx/components.py

@@ -0,0 +1,1661 @@
+"""Sphynx-owned port of the source contracts; no sibling runtime dependency."""
+from __future__ import annotations
+from typing import Any
+JsonValue = Any
+
+def canonical_json_bytes(value):
+    return json.dumps(value, allow_nan=False, ensure_ascii=False, separators=(",", ":"), sort_keys=True).encode("utf-8")
+def json_sha256(value):
+    return hashlib.sha256(canonical_json_bytes(value)).hexdigest()
+"""Versioned RAG component catalog and controlled batch-plan contracts.
+
+The contract is intentionally declarative.  It identifies implementations by registry
+ID (or bounded command argv) and never dynamically imports or executes manifest data.
+"""
+import hashlib
+import json
+import math
+import re
+from collections.abc import Mapping
+from dataclasses import dataclass
+from pathlib import Path, PurePosixPath, PureWindowsPath
+from typing import Any, Literal, cast
+COMPONENT_MANIFEST_SCHEMA_VERSION = 'sable.rag.component-manifest.v1'
+EXPERIMENT_MANIFEST_SCHEMA_VERSION = 'sable.rag.experiment-manifest.v1'
+DEFAULT_MODEL_POLICY_ID = 'minilm-jina-training-free-v1'
+ComponentKind = Literal['chunker', 'dedup', 'embedder', 'full_rag_subject', 'fusion', 'gate', 'generator', 'reranker', 'retriever', 'rewriter', 'router']
+ImplementationKind = Literal['builtin', 'command', 'recorded']
+EvaluationLevel = Literal['level1', 'level2', 'level3']
+EvaluationTrack = Literal['chunking', 'full_rag', 'pipeline', 'reranking', 'retrieval']
+ComparisonMode = Literal['multi_component_diagnostic', 'single_component']
+COMPONENT_KINDS: tuple[ComponentKind, ...] = ('chunker', 'embedder', 'retriever', 'reranker', 'fusion', 'dedup', 'gate', 'router', 'rewriter', 'generator', 'full_rag_subject')
+IMPLEMENTATION_KINDS = frozenset({'builtin', 'command', 'recorded'})
+TARGETS: dict[str, frozenset[str]] = {'level1': frozenset({'chunking', 'retrieval', 'reranking'}), 'level2': frozenset({'pipeline'}), 'level3': frozenset({'full_rag'})}
+manifest_COMPONENT_KIND_SET = frozenset(COMPONENT_KINDS)
+manifest_TARGET_CAPABLE_KINDS: dict[tuple[str, str], frozenset[str]] = {('level1', 'chunking'): frozenset({'chunker'}), ('level1', 'retrieval'): frozenset({'embedder', 'retriever'}), ('level1', 'reranking'): frozenset({'fusion', 'reranker'}), ('level2', 'pipeline'): frozenset({'chunker', 'dedup', 'embedder', 'fusion', 'gate', 'reranker', 'retriever'}), ('level3', 'full_rag'): manifest_COMPONENT_KIND_SET}
+manifest_REQUIRED_KINDS: dict[tuple[str, str], frozenset[str]] = {('level1', 'chunking'): frozenset({'chunker'}), ('level1', 'retrieval'): frozenset({'embedder', 'retriever'}), ('level1', 'reranking'): frozenset({'reranker'}), ('level2', 'pipeline'): frozenset({'chunker', 'dedup', 'embedder', 'fusion', 'gate', 'reranker', 'retriever'}), ('level3', 'full_rag'): frozenset({'full_rag_subject'})}
+manifest_MODEL_DECLARATION_REQUIRED_KINDS = frozenset({'embedder', 'generator', 'reranker'})
+manifest_DEFAULT_RERANKER_FAMILIES = frozenset({'jina', 'minilm'})
+manifest_SAFE_ID = re.compile('[a-z0-9][a-z0-9_-]{0,63}')
+manifest_VERSION = re.compile('[A-Za-z0-9][A-Za-z0-9._+-]{0,127}')
+manifest_SHA256 = re.compile('[0-9a-f]{64}')
+
+class ComponentManifestError(ValueError):
+    """Raised when a component or batch manifest violates a control invariant."""
+
+def manifest_mapping(value: object, context: str) -> Mapping[str, object]:
+    if not isinstance(value, Mapping) or any((not isinstance(key, str) for key in value)):
+        raise ComponentManifestError(f'{context} must be an object with string keys')
+    return cast('Mapping[str, object]', value)
+
+def manifest_exact_keys(value: Mapping[str, object], required: frozenset[str], context: str) -> None:
+    missing = sorted(required - value.keys())
+    extra = sorted(value.keys() - required)
+    if missing or extra:
+        details: list[str] = []
+        if missing:
+            details.append(f"missing keys: {', '.join(missing)}")
+        if extra:
+            details.append(f"extra keys: {', '.join(extra)}")
+        raise ComponentManifestError(f"{context} has {'; '.join(details)}")
+
+def manifest_text(value: object, context: str) -> str:
+    if not isinstance(value, str) or not value.strip():
+        raise ComponentManifestError(f'{context} must be a non-empty string')
+    return value
+
+def manifest_safe_id(value: object, context: str) -> str:
+    text = manifest_text(value, context)
+    if manifest_SAFE_ID.fullmatch(text) is None:
+        raise ComponentManifestError(f'{context} must be a privacy-safe lowercase ID')
+    return text
+
+def manifest_version(value: object, context: str) -> str:
+    text = manifest_text(value, context)
+    if manifest_VERSION.fullmatch(text) is None:
+        raise ComponentManifestError(f'{context} must be a pinned version identifier')
+    return text
+
+def _manifest_sha256(value: object, context: str) -> str:
+    text = manifest_text(value, context)
+    if manifest_SHA256.fullmatch(text) is None:
+        raise ComponentManifestError(f'{context} must be a lowercase SHA-256 digest')
+    return text
+
+def manifest_boolean(value: object, context: str) -> bool:
+    if not isinstance(value, bool):
+        raise ComponentManifestError(f'{context} must be a boolean')
+    return value
+
+def manifest_json_value(value: object, context: str) -> JsonValue:
+    if value is None or isinstance(value, str | bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise ComponentManifestError(f'{context} contains a non-finite number')
+        return value
+    if isinstance(value, list):
+        return [manifest_json_value(item, f'{context}[{index}]') for index, item in enumerate(value)]
+    if isinstance(value, Mapping) and all((isinstance(key, str) for key in value)):
+        string_mapping = cast('Mapping[str, object]', value)
+        return {key: manifest_json_value(item, f'{context}.{key}') for key, item in sorted(string_mapping.items())}
+    raise ComponentManifestError(f'{context} must contain only JSON values')
+
+def manifest_string_list(value: object, context: str, *, nonempty: bool=True, unique: bool=True) -> tuple[str, ...]:
+    if not isinstance(value, list) or (nonempty and (not value)):
+        raise ComponentManifestError(f'{context} must be an array')
+    result = tuple((manifest_text(item, f'{context}[{index}]') for index, item in enumerate(value)))
+    if unique and len(result) != len(set(result)):
+        raise ComponentManifestError(f'{context} must contain unique values')
+    return result
+
+def manifest_absolute_executable(value: str) -> bool:
+    return PurePosixPath(value).is_absolute() or PureWindowsPath(value).is_absolute()
+
+
+def _record_mapping(value):
+    from dataclasses import fields
+    return {field.name: getattr(value, field.name) for field in fields(value)}
+
+
+def _sequence(value, context, item_type, *, nonempty=False):
+    if not isinstance(value, (list, tuple)):
+        raise ComponentManifestError(f'{context} must be a list or tuple')
+    result = tuple(value)
+    if (nonempty and not result) or any(type(item) is not item_type for item in result):
+        raise ComponentManifestError(f'{context} contains invalid values')
+    return result
+
+
+def _byte_object(value):
+    from ._track_capture import strict_json
+    if not isinstance(value, (bytes, bytearray, memoryview)):
+        raise ComponentManifestError('manifest content must be bytes')
+    encoded = bytes(value)
+    try:
+        raw = strict_json(encoded)
+    except ValueError as error:
+        raise ComponentManifestError('manifest content must be strict JSON') from error
+    manifest_mapping(raw, 'manifest content')
+    return encoded, raw
+
+
+def _install_fields(value, names, normalized):
+    for name, item in zip(names, normalized, strict=True):
+        object.__setattr__(value, name, item)
+
+
+@dataclass(frozen=True, slots=True, order=True)
+class EvaluationTarget:
+    """One independently runnable causal level and track."""
+    level: EvaluationLevel
+    track: EvaluationTrack
+
+    def __post_init__(self) -> None:
+        raw = _record_mapping(self)
+        _install_fields(self, raw, _manifest_parse_target_fields(raw, 'EvaluationTarget'))
+
+    @property
+    def key(self) -> tuple[str, str]:
+        return (self.level, self.track)
+
+@dataclass(frozen=True, slots=True)
+class ImplementationSpec:
+    """Pinned implementation identity; no locator is interpreted by this module."""
+    kind: ImplementationKind
+    implementation_id: str
+    version: str
+    artifact_sha256: str
+    argv: tuple[str, ...]
+    def __post_init__(self) -> None:
+        raw = _record_mapping(self)
+        raw['argv'] = list(_sequence(self.argv, 'implementation.argv', str))
+        _install_fields(self, raw, _manifest_parse_implementation_fields(raw, 'ImplementationSpec'))
+
+
+@dataclass(frozen=True, slots=True)
+class ModelSpec:
+    """Explicit model identity and whether an evaluation would require training."""
+    provider: str
+    family: str
+    model_id: str
+    revision: str
+    artifact_sha256: str
+    training_required: bool
+    def __post_init__(self) -> None:
+        raw = _record_mapping(self)
+        _install_fields(self, raw, _manifest_parse_model_fields(raw, 'ModelSpec'))
+
+
+@dataclass(frozen=True, slots=True)
+class ResourceContext:
+    """Pinned execution conditions required for comparable latency measurements."""
+    hardware: str
+    device: str
+    precision: str
+    batch_size: int
+    candidate_depth: int
+    warmup_runs: int
+    measurement_method: str
+    timeout_seconds: float
+    def __post_init__(self) -> None:
+        raw = _record_mapping(self)
+        _install_fields(self, raw, _manifest_parse_resource_context_fields(raw, 'ResourceContext'))
+
+
+@dataclass(frozen=True, slots=True)
+class ComponentSpec:
+    """One immutable, registry-addressed component configuration."""
+    component_id: str
+    version: str
+    kind: ComponentKind
+    implementation: ImplementationSpec
+    _config_bytes: bytes
+    config_sha256: str
+    resource_context: ResourceContext
+    capabilities: tuple[EvaluationTarget, ...]
+    model: ModelSpec | None
+
+    def __post_init__(self) -> None:
+        if type(self.implementation) is not ImplementationSpec or type(self.resource_context) is not ResourceContext or (self.model is not None and type(self.model) is not ModelSpec):
+            raise ComponentManifestError('component implementation, resource context or model is invalid')
+        _, config = _byte_object(self._config_bytes)
+        capabilities = _sequence(self.capabilities, 'component.capabilities', EvaluationTarget, nonempty=True)
+        raw = _record_mapping(self)
+        raw.pop('_config_bytes')
+        raw['config'] = config
+        raw['implementation'] = _record_mapping(self.implementation)
+        raw['implementation']['argv'] = list(self.implementation.argv)
+        raw['resource_context'] = _record_mapping(self.resource_context)
+        raw['model'] = None if self.model is None else _record_mapping(self.model)
+        raw['capabilities'] = [_record_mapping(item) for item in capabilities]
+        normalized = _manifest_parse_component_fields(raw, 'component')
+        _install_fields(self, _record_mapping(self), normalized)
+
+    @property
+    def config(self) -> dict[str, JsonValue]:
+        """Return a detached copy; callers cannot mutate the hash-bound configuration."""
+        return manifest_decode_object(self._config_bytes)
+
+@dataclass(frozen=True, slots=True)
+class ComponentManifest:
+    """Validated component registry whose hash pins a batch plan's full catalog."""
+    _value_bytes: bytes
+    manifest_id: str
+    version: str
+    components: tuple[ComponentSpec, ...]
+
+    def __post_init__(self) -> None:
+        encoded, raw = _byte_object(self._value_bytes)
+        components = _sequence(self.components, 'components', ComponentSpec, nonempty=True)
+        expected = _validate_component_manifest_fields(raw)
+        if (self.manifest_id, self.version, components) != expected[1:]:
+            raise ComponentManifestError('exposed component records differ from committed manifest bytes')
+        object.__setattr__(self, '_value_bytes', encoded)
+        object.__setattr__(self, 'components', components)
+
+    @property
+    def sha256(self) -> str:
+        return hashlib.sha256(self._value_bytes).hexdigest()
+
+    @property
+    def value(self) -> dict[str, JsonValue]:
+        """Return a detached manifest copy while immutable canonical bytes remain authoritative."""
+        return manifest_decode_object(self._value_bytes)
+
+    @property
+    def by_id(self) -> dict[str, ComponentSpec]:
+        return {component.component_id: component for component in self.components}
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        return manifest_decode_object(self._value_bytes)
+
+@dataclass(frozen=True, slots=True)
+class ComponentRef:
+    """Batch-plan pin to one catalog component."""
+    kind: ComponentKind
+    component_id: str
+    component_version: str
+    config_sha256: str
+
+    def __post_init__(self) -> None:
+        kind = manifest_text(self.kind, 'component reference kind')
+        if kind not in manifest_COMPONENT_KIND_SET:
+            raise ComponentManifestError('component reference kind is invalid')
+        manifest_safe_id(self.component_id, 'component reference ID')
+        manifest_version(self.component_version, 'component reference version')
+        _manifest_sha256(self.config_sha256, 'component reference config digest')
+
+    @property
+    def identity(self) -> tuple[str, str, str]:
+        return (self.component_id, self.component_version, self.config_sha256)
+
+@dataclass(frozen=True, slots=True)
+class ExperimentConfiguration:
+    """A complete assignment of component kinds to pinned catalog entries."""
+    configuration_id: str
+    components: tuple[ComponentRef, ...]
+
+    def __post_init__(self) -> None:
+        manifest_safe_id(self.configuration_id, 'configuration ID')
+        components = _sequence(self.components, 'configuration components', ComponentRef, nonempty=True)
+        if len({item.kind for item in components}) != len(components):
+            raise ComponentManifestError('configuration has duplicate component kinds')
+        object.__setattr__(self, 'components', components)
+
+    @property
+    def by_kind(self) -> dict[ComponentKind, ComponentRef]:
+        return {component.kind: component for component in self.components}
+
+@dataclass(frozen=True, slots=True)
+class ComponentChange:
+    """A change derived from exact baseline and alternative component identities."""
+    kind: ComponentKind
+    baseline: ComponentRef
+    alternative: ComponentRef
+    def __post_init__(self) -> None:
+        if type(self.baseline) is not ComponentRef or type(self.alternative) is not ComponentRef:
+            raise ComponentManifestError('component changes require component references')
+        if self.kind != self.baseline.kind or self.kind != self.alternative.kind or self.baseline.identity == self.alternative.identity:
+            raise ComponentManifestError('component change must bind different identities of the same kind')
+
+
+@dataclass(frozen=True, slots=True)
+class ExperimentAlternative:
+    """Named alternative with manifest-verified declared changes."""
+    alternative_id: str
+    comparison_mode: ComparisonMode
+    configuration: ExperimentConfiguration
+    changes: tuple[ComponentChange, ...]
+
+    def __post_init__(self) -> None:
+        manifest_safe_id(self.alternative_id, 'alternative ID')
+        mode = manifest_text(self.comparison_mode, 'comparison mode')
+        if mode not in {'single_component', 'multi_component_diagnostic'} or type(self.configuration) is not ExperimentConfiguration:
+            raise ComponentManifestError('invalid alternative mode or configuration')
+        changes = _sequence(self.changes, 'alternative changes', ComponentChange, nonempty=True)
+        if len({change.kind for change in changes}) != len(changes):
+            raise ComponentManifestError('alternative changes must have unique kinds')
+        if (mode == 'single_component' and len(changes) != 1) or (mode == 'multi_component_diagnostic' and len(changes) < 2):
+            raise ComponentManifestError('alternative change count differs from comparison mode')
+        if any(self.configuration.by_kind.get(change.kind) != change.alternative for change in changes):
+            raise ComponentManifestError('alternative changes differ from its configuration')
+        object.__setattr__(self, 'changes', changes)
+
+    @property
+    def decision_eligible(self) -> bool:
+        return self.comparison_mode == 'single_component'
+
+@dataclass(frozen=True, slots=True)
+class ExperimentManifest:
+    """Native batch plan over baseline/alternatives and runnable RAG targets.
+
+    BatchPlan is the canonical equivalent alias. Native experiment_id fields,
+    schema IDs, canonical bytes, and identity checks retain their meaning.
+    """
+    _value_bytes: bytes
+    experiment_id: str
+    version: str
+    component_manifest_sha256: str
+    targets: tuple[EvaluationTarget, ...]
+    baseline: ExperimentConfiguration
+    alternatives: tuple[ExperimentAlternative, ...]
+
+    def __post_init__(self) -> None:
+        encoded, raw = _byte_object(self._value_bytes)
+        targets = _sequence(self.targets, 'experiment targets', EvaluationTarget, nonempty=True)
+        alternatives = _sequence(self.alternatives, 'experiment alternatives', ExperimentAlternative, nonempty=True)
+        if type(self.baseline) is not ExperimentConfiguration:
+            raise ComponentManifestError('experiment baseline is invalid')
+        expected = _validate_experiment_manifest_fields(raw, None)
+        if (self.experiment_id, self.version, self.component_manifest_sha256, targets, self.baseline, alternatives) != expected[1:]:
+            raise ComponentManifestError('exposed experiment records differ from committed manifest bytes')
+        object.__setattr__(self, '_value_bytes', encoded)
+        object.__setattr__(self, 'targets', targets)
+        object.__setattr__(self, 'alternatives', alternatives)
+
+    @property
+    def sha256(self) -> str:
+        return hashlib.sha256(self._value_bytes).hexdigest()
+
+    @property
+    def value(self) -> dict[str, JsonValue]:
+        """Return a detached copy of the validated native batch declaration."""
+        return manifest_decode_object(self._value_bytes)
+
+    def changes_for(self, alternative_id: str) -> tuple[ComponentChange, ...]:
+        for alternative in self.alternatives:
+            if alternative.alternative_id == alternative_id:
+                return alternative.changes
+        raise KeyError(alternative_id)
+
+    def to_mapping(self) -> dict[str, JsonValue]:
+        return manifest_decode_object(self._value_bytes)
+
+def manifest_decode_object(encoded: bytes) -> dict[str, JsonValue]:
+    return _byte_object(encoded)[1]
+
+
+def _manifest_parse_target_fields(raw: object, context: str):
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'level', 'track'}), context)
+    level_text = manifest_text(value['level'], f'{context}.level')
+    track_text = manifest_text(value['track'], f'{context}.track')
+    if level_text not in TARGETS:
+        raise ComponentManifestError(f'{context}.level is invalid')
+    if track_text not in TARGETS[level_text]:
+        raise ComponentManifestError(f'{context}.track is invalid for {level_text}')
+    return (cast('EvaluationLevel', level_text), cast('EvaluationTrack', track_text))
+
+def manifest_parse_target(raw: object, context: str) -> EvaluationTarget:
+    return EvaluationTarget(*_manifest_parse_target_fields(raw, context))
+
+def _manifest_parse_implementation_fields(raw: object, context: str):
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'kind', 'implementation_id', 'version', 'artifact_sha256', 'argv'}), context)
+    kind_text = manifest_text(value['kind'], f'{context}.kind')
+    if kind_text not in IMPLEMENTATION_KINDS:
+        raise ComponentManifestError(f'{context}.kind is invalid')
+    argv = manifest_string_list(value['argv'], f'{context}.argv', nonempty=False, unique=False)
+    if len(argv) > 32 or any((len(argument) > 4096 or '\x00' in argument for argument in argv)):
+        raise ComponentManifestError(f'{context}.argv exceeds the bounded command contract')
+    if kind_text == 'command':
+        if not argv or not manifest_absolute_executable(argv[0]):
+            raise ComponentManifestError(f'{context}.argv needs an absolute executable for command implementations')
+    elif argv:
+        raise ComponentManifestError(f'{context}.argv must be empty unless implementation kind is command')
+    return (cast('ImplementationKind', kind_text), manifest_safe_id(value['implementation_id'], f'{context}.implementation_id'), manifest_version(value['version'], f'{context}.version'), _manifest_sha256(value['artifact_sha256'], f'{context}.artifact_sha256'), argv)
+
+def manifest_parse_implementation(raw: object, context: str) -> ImplementationSpec:
+    return ImplementationSpec(*_manifest_parse_implementation_fields(raw, context))
+
+def _manifest_parse_model_fields(raw: object, context: str):
+    if raw is None:
+        return None
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'provider', 'family', 'model_id', 'revision', 'artifact_sha256', 'training_required'}), context)
+    return (manifest_safe_id(value['provider'], f'{context}.provider'), manifest_safe_id(value['family'], f'{context}.family'), manifest_text(value['model_id'], f'{context}.model_id'), manifest_version(value['revision'], f'{context}.revision'), _manifest_sha256(value['artifact_sha256'], f'{context}.artifact_sha256'), manifest_boolean(value['training_required'], f'{context}.training_required'))
+
+def manifest_parse_model(raw: object, context: str) -> ModelSpec | None:
+    fields = _manifest_parse_model_fields(raw, context)
+    return None if fields is None else ModelSpec(*fields)
+
+def manifest_integer_at_least(value: object, minimum: int, context: str) -> int:
+    if isinstance(value, bool) or not isinstance(value, int) or value < minimum:
+        raise ComponentManifestError(f'{context} must be an integer >= {minimum}')
+    return value
+
+def _manifest_parse_resource_context_fields(raw: object, context: str):
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'hardware', 'device', 'precision', 'batch_size', 'candidate_depth', 'warmup_runs', 'measurement_method', 'timeout_seconds'}), context)
+    timeout = value['timeout_seconds']
+    if isinstance(timeout, bool) or not isinstance(timeout, int | float) or (not math.isfinite(float(timeout))) or (not 0 < float(timeout) <= 3600):
+        raise ComponentManifestError(f'{context}.timeout_seconds must be finite in (0, 3600]')
+    return (manifest_text(value['hardware'], f'{context}.hardware'), manifest_safe_id(value['device'], f'{context}.device'), manifest_safe_id(value['precision'], f'{context}.precision'), manifest_integer_at_least(value['batch_size'], 1, f'{context}.batch_size'), manifest_integer_at_least(value['candidate_depth'], 0, f'{context}.candidate_depth'), manifest_integer_at_least(value['warmup_runs'], 0, f'{context}.warmup_runs'), manifest_safe_id(value['measurement_method'], f'{context}.measurement_method'), float(timeout))
+
+def manifest_parse_resource_context(raw: object, context: str) -> ResourceContext:
+    return ResourceContext(*_manifest_parse_resource_context_fields(raw, context))
+
+def _manifest_parse_component_fields(raw: object, context: str):
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'component_id', 'version', 'kind', 'implementation', 'config', 'config_sha256', 'resource_context', 'capabilities', 'model'}), context)
+    kind_text = manifest_text(value['kind'], f'{context}.kind')
+    if kind_text not in manifest_COMPONENT_KIND_SET:
+        raise ComponentManifestError(f'{context}.kind is invalid')
+    kind = cast('ComponentKind', kind_text)
+    config = manifest_json_value(value['config'], f'{context}.config')
+    if not isinstance(config, dict):
+        raise ComponentManifestError(f'{context}.config must be an object')
+    config_sha256 = _manifest_sha256(value['config_sha256'], f'{context}.config_sha256')
+    if config_sha256 != json_sha256(config):
+        raise ComponentManifestError(f'{context}.config_sha256 does not bind config')
+    capabilities_raw = value['capabilities']
+    if not isinstance(capabilities_raw, list) or not capabilities_raw:
+        raise ComponentManifestError(f'{context}.capabilities must be a non-empty array')
+    capabilities = tuple((manifest_parse_target(item, f'{context}.capabilities[{index}]') for index, item in enumerate(capabilities_raw)))
+    if len(capabilities) != len(set(capabilities)):
+        raise ComponentManifestError(f'{context}.capabilities must be unique')
+    for capability in capabilities:
+        if kind not in manifest_TARGET_CAPABLE_KINDS[capability.key]:
+            raise ComponentManifestError(f'{context} kind {kind} has a capability/level mismatch for {capability.level}/{capability.track}')
+    model = manifest_parse_model(value['model'], f'{context}.model')
+    if kind in manifest_MODEL_DECLARATION_REQUIRED_KINDS and model is None:
+        raise ComponentManifestError(f'{context} kind {kind} must declare its model')
+    return (manifest_safe_id(value['component_id'], f'{context}.component_id'), manifest_version(value['version'], f'{context}.version'), kind, manifest_parse_implementation(value['implementation'], f'{context}.implementation'), canonical_json_bytes(config), config_sha256, manifest_parse_resource_context(value['resource_context'], f'{context}.resource_context'), capabilities, model)
+
+def manifest_parse_component(raw: object, context: str) -> ComponentSpec:
+    return ComponentSpec(*_manifest_parse_component_fields(raw, context))
+
+def _validate_component_manifest_fields(raw: object):
+    """Validate and normalize a versioned component catalog without loading code."""
+    root = manifest_mapping(raw, 'component manifest')
+    manifest_exact_keys(root, frozenset({'schema_version', 'manifest_id', 'version', 'components'}), 'component manifest')
+    if manifest_text(root['schema_version'], 'schema_version') != COMPONENT_MANIFEST_SCHEMA_VERSION:
+        raise ComponentManifestError(f'schema_version must be {COMPONENT_MANIFEST_SCHEMA_VERSION}')
+    components_raw = root['components']
+    if not isinstance(components_raw, list) or not components_raw:
+        raise ComponentManifestError('components must be a non-empty array')
+    components = tuple((manifest_parse_component(item, f'components[{index}]') for index, item in enumerate(components_raw)))
+    component_ids = tuple((component.component_id for component in components))
+    if len(component_ids) != len(set(component_ids)):
+        raise ComponentManifestError('component_id values must be unique')
+    normalized = manifest_json_value(root, 'component manifest')
+    if not isinstance(normalized, dict):
+        raise AssertionError('validated component manifest must remain an object')
+    return (canonical_json_bytes(normalized), manifest_safe_id(root['manifest_id'], 'manifest_id'), manifest_version(root['version'], 'version'), components)
+
+def validate_component_manifest(raw: object) -> ComponentManifest:
+    """Validate and snapshot a catalog without loading component code."""
+    return ComponentManifest(*_validate_component_manifest_fields(raw))
+
+def manifest_parse_component_ref(raw: object, context: str, catalog: Mapping[str, ComponentSpec] | None) -> ComponentRef:
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'kind', 'component_id', 'component_version', 'config_sha256'}), context)
+    kind_text = manifest_text(value['kind'], f'{context}.kind')
+    if kind_text not in manifest_COMPONENT_KIND_SET:
+        raise ComponentManifestError(f'{context}.kind is invalid')
+    kind = cast('ComponentKind', kind_text)
+    component_id = manifest_safe_id(value['component_id'], f'{context}.component_id')
+    if catalog is None:
+        return ComponentRef(kind, component_id, value['component_version'], value['config_sha256'])
+    component = catalog.get(component_id)
+    if component is None:
+        raise ComponentManifestError(f'{context} references unknown component {component_id}')
+    version = manifest_version(value['component_version'], f'{context}.component_version')
+    config_sha256 = _manifest_sha256(value['config_sha256'], f'{context}.config_sha256')
+    if kind != component.kind:
+        raise ComponentManifestError(f'{context}.kind does not match the catalog component')
+    if version != component.version:
+        raise ComponentManifestError(f'{context}.component_version does not match the catalog')
+    if config_sha256 != component.config_sha256:
+        raise ComponentManifestError(f'{context}.config_sha256 does not match the catalog')
+    return ComponentRef(kind, component_id, version, config_sha256)
+
+def manifest_parse_configuration(raw: object, context: str, catalog: Mapping[str, ComponentSpec] | None) -> ExperimentConfiguration:
+    value = manifest_mapping(raw, context)
+    manifest_exact_keys(value, frozenset({'configuration_id', 'components'}), context)
+    components_raw = value['components']
+    if not isinstance(components_raw, list) or not components_raw:
+        raise ComponentManifestError(f'{context}.components must be a non-empty array')
+    components = tuple((manifest_parse_component_ref(item, f'{context}.components[{index}]', catalog) for index, item in enumerate(components_raw)))
+    kinds = tuple((component.kind for component in components))
+    if len(kinds) != len(set(kinds)):
+        raise ComponentManifestError(f'{context} has duplicate component kinds')
+    return ExperimentConfiguration(manifest_safe_id(value['configuration_id'], f'{context}.configuration_id'), components)
+
+def manifest_validate_selection(raw: object) -> None:
+    selection = manifest_mapping(raw, 'configuration_selection')
+    manifest_exact_keys(selection, frozenset({'mode', 'scope', 'uses_query_or_task_features', 'uses_gold_or_evaluation_labels'}), 'configuration_selection')
+    if manifest_text(selection['mode'], 'configuration_selection.mode') != 'predeclared_global':
+        raise ComponentManifestError('configuration selection must be predeclared_global, never per-query')
+    if manifest_text(selection['scope'], 'configuration_selection.scope') != 'experiment':
+        raise ComponentManifestError('configuration selection scope must be experiment')
+    if manifest_boolean(selection['uses_query_or_task_features'], 'configuration_selection.uses_query_or_task_features'):
+        raise ComponentManifestError('per-query or per-task configuration selection is forbidden')
+    if manifest_boolean(selection['uses_gold_or_evaluation_labels'], 'configuration_selection.uses_gold_or_evaluation_labels'):
+        raise ComponentManifestError('gold-informed configuration selection is forbidden')
+
+def manifest_validate_default_model_policy(raw: object) -> None:
+    policy = manifest_mapping(raw, 'model_policy')
+    manifest_exact_keys(policy, frozenset({'policy_id', 'allowed_reranker_families', 'training_allowed', 'require_reranker_model_declaration'}), 'model_policy')
+    if manifest_text(policy['policy_id'], 'model_policy.policy_id') != DEFAULT_MODEL_POLICY_ID:
+        raise ComponentManifestError(f'model_policy.policy_id must be {DEFAULT_MODEL_POLICY_ID}')
+    families = manifest_string_list(policy['allowed_reranker_families'], 'model_policy.allowed_reranker_families')
+    if frozenset(families) != manifest_DEFAULT_RERANKER_FAMILIES:
+        raise ComponentManifestError('default model policy allows only MiniLM and Jina rerankers')
+    if manifest_boolean(policy['training_allowed'], 'model_policy.training_allowed'):
+        raise ComponentManifestError('default model policy cannot allow training')
+    if not manifest_boolean(policy['require_reranker_model_declaration'], 'model_policy.require_reranker_model_declaration'):
+        raise ComponentManifestError('default model policy requires declared reranker models')
+
+def manifest_validate_configuration_for_targets(configuration: ExperimentConfiguration, targets: tuple[EvaluationTarget, ...], catalog: Mapping[str, ComponentSpec] | None) -> None:
+    by_kind = configuration.by_kind
+    for target in targets:
+        missing = sorted(manifest_REQUIRED_KINDS[target.key] - by_kind.keys())
+        if missing:
+            raise ComponentManifestError(f"configuration {configuration.configuration_id} is missing required components for {target.level}/{target.track}: {', '.join(missing)}")
+        if catalog is None:
+            continue
+        for kind in manifest_REQUIRED_KINDS[target.key]:
+            component = catalog[by_kind[cast('ComponentKind', kind)].component_id]
+            if target not in component.capabilities:
+                raise ComponentManifestError(f'component {component.component_id} has a capability/level mismatch for {target.level}/{target.track}')
+
+def manifest_validate_selected_models(configurations: tuple[ExperimentConfiguration, ...], catalog: Mapping[str, ComponentSpec]) -> None:
+    selected_ids = {reference.component_id for configuration in configurations for reference in configuration.components}
+    for component_id in sorted(selected_ids):
+        component = catalog[component_id]
+        if component.model is not None and component.model.training_required:
+            raise ComponentManifestError(f'component {component_id} requires training, which the default policy forbids')
+        if component.kind == 'reranker':
+            if component.model is None:
+                raise ComponentManifestError(f'reranker {component_id} must declare a model under the default policy')
+            if component.model.family not in manifest_DEFAULT_RERANKER_FAMILIES:
+                raise ComponentManifestError(f'reranker {component_id} uses undeclared model family {component.model.family}; only MiniLM and Jina are allowed')
+
+def manifest_derive_changes(baseline: ExperimentConfiguration, alternative: ExperimentConfiguration) -> tuple[ComponentChange, ...]:
+    baseline_by_kind = baseline.by_kind
+    alternative_by_kind = alternative.by_kind
+    if baseline_by_kind.keys() != alternative_by_kind.keys():
+        raise ComponentManifestError(f'alternative {alternative.configuration_id} must assign exactly the baseline kinds')
+    changes: list[ComponentChange] = []
+    for kind in COMPONENT_KINDS:
+        before = baseline_by_kind.get(kind)
+        if before is None:
+            continue
+        after = alternative_by_kind[kind]
+        if before.identity != after.identity:
+            changes.append(ComponentChange(kind, before, after))
+    if not changes:
+        raise ComponentManifestError(f'alternative {alternative.configuration_id} is identical to the baseline')
+    return tuple(changes)
+
+def _validate_experiment_manifest_fields(raw: object, component_manifest: ComponentManifest | None):
+    """Validate a fixed native batch plan and derive its component deltas."""
+    root = manifest_mapping(raw, 'experiment manifest')
+    manifest_exact_keys(root, frozenset({'schema_version', 'experiment_id', 'version', 'component_manifest', 'targets', 'configuration_selection', 'model_policy', 'baseline', 'alternatives'}), 'experiment manifest')
+    if manifest_text(root['schema_version'], 'schema_version') != EXPERIMENT_MANIFEST_SCHEMA_VERSION:
+        raise ComponentManifestError(f'schema_version must be {EXPERIMENT_MANIFEST_SCHEMA_VERSION}')
+    catalog_ref = manifest_mapping(root['component_manifest'], 'component_manifest')
+    manifest_exact_keys(catalog_ref, frozenset({'manifest_id', 'version', 'sha256'}), 'component_manifest')
+    catalog_id = manifest_safe_id(catalog_ref['manifest_id'], 'component_manifest.manifest_id')
+    if component_manifest is not None and catalog_id != component_manifest.manifest_id:
+        raise ComponentManifestError('component manifest ID does not match the catalog')
+    catalog_version = manifest_version(catalog_ref['version'], 'component_manifest.version')
+    if component_manifest is not None and catalog_version != component_manifest.version:
+        raise ComponentManifestError('component manifest version does not match the catalog')
+    manifest_sha256 = _manifest_sha256(catalog_ref['sha256'], 'component_manifest.sha256')
+    if component_manifest is not None and manifest_sha256 != component_manifest.sha256:
+        raise ComponentManifestError('component manifest SHA-256 does not match the catalog')
+    targets_raw = root['targets']
+    if not isinstance(targets_raw, list) or not targets_raw:
+        raise ComponentManifestError('targets must be a non-empty array')
+    targets = tuple((manifest_parse_target(item, f'targets[{index}]') for index, item in enumerate(targets_raw)))
+    if len(targets) != len(set(targets)):
+        raise ComponentManifestError('targets must be unique')
+    manifest_validate_selection(root['configuration_selection'])
+    manifest_validate_default_model_policy(root['model_policy'])
+    catalog = None if component_manifest is None else component_manifest.by_id
+    baseline = manifest_parse_configuration(root['baseline'], 'baseline', catalog)
+    manifest_validate_configuration_for_targets(baseline, targets, catalog)
+    alternatives_raw = root['alternatives']
+    if not isinstance(alternatives_raw, list) or not alternatives_raw:
+        raise ComponentManifestError('alternatives must be a non-empty array')
+    alternatives: list[ExperimentAlternative] = []
+    for index, raw_alternative in enumerate(alternatives_raw):
+        context = f'alternatives[{index}]'
+        value = manifest_mapping(raw_alternative, context)
+        manifest_exact_keys(value, frozenset({'alternative_id', 'comparison_mode', 'declared_changed_kinds', 'configuration'}), context)
+        alternative_id = manifest_safe_id(value['alternative_id'], f'{context}.alternative_id')
+        mode_text = manifest_text(value['comparison_mode'], f'{context}.comparison_mode')
+        if mode_text not in {'multi_component_diagnostic', 'single_component'}:
+            raise ComponentManifestError(f'{context}.comparison_mode is invalid')
+        mode = cast('ComparisonMode', mode_text)
+        configuration = manifest_parse_configuration(value['configuration'], f'{context}.configuration', catalog)
+        manifest_validate_configuration_for_targets(configuration, targets, catalog)
+        changes = manifest_derive_changes(baseline, configuration)
+        declared = manifest_string_list(value['declared_changed_kinds'], f'{context}.declared_changed_kinds')
+        derived = tuple((change.kind for change in changes))
+        if declared != derived:
+            raise ComponentManifestError(f"{context}.declared_changed_kinds does not match exact derived changes: {', '.join(derived)}")
+        if mode == 'single_component' and len(changes) != 1:
+            raise ComponentManifestError(f'{context} single_component comparison must change exactly one component')
+        if mode == 'multi_component_diagnostic' and len(changes) < 2:
+            raise ComponentManifestError(f'{context} multi_component_diagnostic must change at least two components')
+        if any((target.level == 'level2' for target in targets)) and mode != 'single_component':
+            raise ComponentManifestError(f'{context} Level 2 comparisons must change one component at a time')
+        for change in changes if catalog is not None else ():
+            before = catalog[change.baseline.component_id]
+            after = catalog[change.alternative.component_id]
+            if not any((target in before.capabilities and target in after.capabilities for target in targets)):
+                raise ComponentManifestError(f'changed component kind {change.kind} has no capability for a declared target')
+        alternatives.append(ExperimentAlternative(alternative_id, mode, configuration, changes))
+    identifiers = [baseline.configuration_id]
+    identifiers.extend((alternative.alternative_id for alternative in alternatives))
+    identifiers.extend((alternative.configuration.configuration_id for alternative in alternatives))
+    if len(identifiers) != len(set(identifiers)):
+        raise ComponentManifestError('baseline, alternative, and configuration IDs must be globally unique')
+    if catalog is not None:
+        manifest_validate_selected_models((baseline, *(alternative.configuration for alternative in alternatives)), catalog)
+    normalized = manifest_json_value(root, 'experiment manifest')
+    if not isinstance(normalized, dict):
+        raise AssertionError('validated experiment manifest must remain an object')
+    return (canonical_json_bytes(normalized), manifest_safe_id(root['experiment_id'], 'experiment_id'), manifest_version(root['version'], 'version'), manifest_sha256, targets, baseline, tuple(alternatives))
+
+def validate_experiment_manifest(raw: object, component_manifest: ComponentManifest) -> ExperimentManifest:
+    """Validate the declaration and every referenced catalog identity and policy."""
+    if type(component_manifest) is not ComponentManifest:
+        raise ComponentManifestError('validated component manifest is required')
+    return ExperimentManifest(*_validate_experiment_manifest_fields(raw, component_manifest))
+
+def manifest_reject_constant(value: str) -> None:
+    raise ComponentManifestError(f'non-finite JSON constant is forbidden: {value}')
+
+def manifest_load_json(path: Path, context: str) -> object:
+    try:
+        return json.loads(path.read_text(encoding='utf-8'), parse_constant=manifest_reject_constant)
+    except (OSError, json.JSONDecodeError) as error:
+        raise ComponentManifestError(f'cannot read {context}: {error}') from error
+
+def load_component_manifest(path: Path) -> ComponentManifest:
+    """Load and validate a local component manifest."""
+    return validate_component_manifest(manifest_load_json(path, 'component manifest'))
+
+def load_experiment_manifest(path: Path, component_manifest: ComponentManifest) -> ExperimentManifest:
+    """Load a native batch plan against an already validated component catalog."""
+    return validate_experiment_manifest(manifest_load_json(path, 'experiment manifest'), component_manifest)
+
+"""Hermetic component adapter SDK for the offline RAG batch workbench.
+
+Adapters are registered code objects, never import paths.  Every registration is
+checked against the already validated component manifest before an invocation can
+run.  The in-process and recorded implementations in this module perform no
+network, subprocess, model-loading, or dynamic-import work.
+"""
+import hashlib
+import json
+import math
+import re
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol, cast, runtime_checkable
+AdapterHandler = Callable[[dict[str, JsonValue]], Mapping[str, object]]
+sdk_SHA256 = re.compile('[0-9a-f]{64}')
+sdk_TOKEN = re.compile('[a-z0-9]+')
+OPERATIONS_BY_KIND: dict[ComponentKind, tuple[str, ...]] = {'chunker': ('chunk',), 'embedder': ('embed',), 'retriever': ('retrieve',), 'reranker': ('rerank',), 'fusion': ('fuse',), 'dedup': ('deduplicate',), 'gate': ('gate',), 'router': ('route',), 'rewriter': ('rewrite',), 'generator': ('generate',), 'full_rag_subject': ('full_rag',)}
+PIPELINE_COMPONENT_ORDER: tuple[ComponentKind, ...] = ('chunker', 'embedder', 'retriever', 'reranker', 'fusion', 'dedup', 'gate')
+SYNTHETIC_IMPLEMENTATION_IDS: dict[ComponentKind, str] = {kind: f"sable-synthetic-{kind.replace('_', '-')}-v1" for kind in COMPONENT_KINDS}
+
+class ComponentSdkError(ValueError):
+    """Base error for invalid descriptors, registrations, and invocations."""
+
+class AdapterRegistrationError(ComponentSdkError):
+    """Raised before execution when an adapter differs from its manifest entry."""
+
+class AdapterInvocationError(ComponentSdkError):
+    """Raised when a bounded adapter request cannot produce a valid JSON result."""
+
+def sdk_json_value(value: object, context: str) -> JsonValue:
+    if value is None or isinstance(value, str | bool):
+        return value
+    if isinstance(value, int):
+        return value
+    if isinstance(value, float):
+        if not math.isfinite(value):
+            raise AdapterInvocationError(f'{context} contains a non-finite number')
+        return value
+    if isinstance(value, list | tuple):
+        return [sdk_json_value(item, f'{context}[{index}]') for index, item in enumerate(value)]
+    if isinstance(value, Mapping) and all((isinstance(key, str) for key in value)):
+        string_mapping = cast('Mapping[str, object]', value)
+        return {key: sdk_json_value(item, f'{context}.{key}') for key, item in sorted(string_mapping.items())}
+    raise AdapterInvocationError(f'{context} must contain only finite JSON values')
+
+def sdk_json_object(value: object, context: str) -> dict[str, JsonValue]:
+    normalized = sdk_json_value(value, context)
+    if not isinstance(normalized, dict):
+        raise AdapterInvocationError(f'{context} must be an object')
+    return normalized
+
+def sdk_clone_object(value: Mapping[str, object], context: str) -> dict[str, JsonValue]:
+    normalized = sdk_json_object(value, context)
+    raw: Any = json.loads(canonical_json_bytes(normalized))
+    return cast('dict[str, JsonValue]', raw)
+
+@dataclass(frozen=True, slots=True)
+class AdapterDescriptor:
+    """Runtime identity bound one-to-one to a component manifest entry."""
+    component_id: str
+    component_version: str
+    component_kind: ComponentKind
+    implementation_id: str
+    implementation_kind: ImplementationKind
+    implementation_version: str
+    implementation_artifact_sha256: str
+    implementation_argv: tuple[str, ...]
+    config_sha256: str
+    resource_context: ResourceContext
+    capabilities: tuple[EvaluationTarget, ...]
+    operations: tuple[str, ...]
+
+    def __post_init__(self) -> None:
+
+        try:
+            ComponentRef(self.component_kind, self.component_id, self.component_version, self.config_sha256)
+            implementation = ImplementationSpec(self.implementation_kind, self.implementation_id, self.implementation_version, self.implementation_artifact_sha256, self.implementation_argv)
+            capabilities = _sequence(self.capabilities, 'adapter capabilities', EvaluationTarget, nonempty=True)
+            operations = _sequence(self.operations, 'adapter operations', str, nonempty=True)
+            if type(self.resource_context) is not ResourceContext:
+                raise ComponentManifestError('adapter resource context is invalid')
+            if any(self.component_kind not in manifest_TARGET_CAPABLE_KINDS[item.key] for item in capabilities):
+                raise ComponentManifestError('adapter capability does not match component kind')
+            object.__setattr__(self, 'implementation_argv', implementation.argv)
+            object.__setattr__(self, 'capabilities', capabilities)
+            object.__setattr__(self, 'operations', operations)
+        except ComponentManifestError as error:
+            raise AdapterRegistrationError(str(error)) from error
+        if not self.component_id or not self.component_version or (not self.implementation_id) or (not self.implementation_version):
+            raise AdapterRegistrationError('adapter descriptor identity must be non-empty')
+        if self.implementation_kind not in {'builtin', 'command', 'recorded'}:
+            raise AdapterRegistrationError('adapter descriptor implementation kind is invalid')
+        if (self.implementation_kind == 'command') != bool(self.implementation_argv):
+            raise AdapterRegistrationError('only command adapter descriptors may declare non-empty argv')
+        if sdk_SHA256.fullmatch(self.implementation_artifact_sha256) is None:
+            raise AdapterRegistrationError('adapter descriptor artifact hash must be SHA-256')
+        if sdk_SHA256.fullmatch(self.config_sha256) is None:
+            raise AdapterRegistrationError('adapter descriptor config hash must be SHA-256')
+        allowed = OPERATIONS_BY_KIND[self.component_kind]
+        if not self.operations or len(self.operations) != len(set(self.operations)):
+            raise AdapterRegistrationError('adapter descriptor operations must be non-empty and unique')
+        if any((operation not in allowed for operation in self.operations)):
+            raise AdapterRegistrationError(f'adapter descriptor operation is invalid for {self.component_kind}')
+        if not self.capabilities or len(self.capabilities) != len(set(self.capabilities)):
+            raise AdapterRegistrationError('adapter descriptor capabilities must be non-empty and unique')
+
+    @classmethod
+    def from_component(cls, component: ComponentSpec) -> AdapterDescriptor:
+        """Derive the only valid default runtime descriptor for a component."""
+        return cls(component.component_id, component.version, component.kind, component.implementation.implementation_id, component.implementation.kind, component.implementation.version, component.implementation.artifact_sha256, component.implementation.argv, component.config_sha256, component.resource_context, component.capabilities, OPERATIONS_BY_KIND[component.kind])
+
+@runtime_checkable
+class ComponentAdapter(Protocol):
+    """Universal synchronous component surface consumed by the workbench."""
+
+    @property
+    def descriptor(self) -> AdapterDescriptor:
+        ...
+
+    @property
+    def capabilities(self) -> tuple[EvaluationTarget, ...]:
+        ...
+
+    def invoke(self, operation: str, payload: Mapping[str, object]) -> dict[str, JsonValue]:
+        ...
+
+def canonical_request_sha256(descriptor: AdapterDescriptor, operation: str, payload: Mapping[str, object]) -> str:
+    """Hash the complete adapter identity, operation, and canonical JSON payload."""
+    if operation not in descriptor.operations:
+        raise AdapterInvocationError(f'operation {operation!r} is not supported by {descriptor.component_id}')
+    normalized = sdk_json_object(payload, 'adapter request payload')
+    request: dict[str, JsonValue] = {'component_id': descriptor.component_id, 'component_version': descriptor.component_version, 'config_sha256': descriptor.config_sha256, 'implementation_argv': list(descriptor.implementation_argv), 'implementation_id': descriptor.implementation_id, 'implementation_version': descriptor.implementation_version, 'operation': operation, 'payload': normalized, 'resource_context': {'hardware': descriptor.resource_context.hardware, 'device': descriptor.resource_context.device, 'precision': descriptor.resource_context.precision, 'batch_size': descriptor.resource_context.batch_size, 'candidate_depth': descriptor.resource_context.candidate_depth, 'warmup_runs': descriptor.resource_context.warmup_runs, 'measurement_method': descriptor.resource_context.measurement_method, 'timeout_seconds': descriptor.resource_context.timeout_seconds}}
+    return hashlib.sha256(canonical_json_bytes(request)).hexdigest()
+
+class FunctionAdapter:
+    """Registered in-process handlers with canonical I/O and replay determinism checks."""
+    __slots__ = ('_descriptor', '_handlers', '_observed')
+
+    def __init__(self, descriptor: AdapterDescriptor, handlers: Mapping[str, AdapterHandler]) -> None:
+        if descriptor.implementation_kind != 'builtin':
+            raise AdapterRegistrationError('FunctionAdapter requires a builtin implementation')
+        if set(handlers) != set(descriptor.operations):
+            raise AdapterRegistrationError('FunctionAdapter handlers must exactly match descriptor operations')
+        self._descriptor = descriptor
+        self._handlers = dict(handlers)
+        self._observed: dict[str, bytes] = {}
+
+    @property
+    def descriptor(self) -> AdapterDescriptor:
+        return self._descriptor
+
+    @property
+    def capabilities(self) -> tuple[EvaluationTarget, ...]:
+        return self._descriptor.capabilities
+
+    def invoke(self, operation: str, payload: Mapping[str, object]) -> dict[str, JsonValue]:
+        handler = self._handlers.get(operation)
+        if handler is None:
+            raise AdapterInvocationError(f'operation {operation!r} is not supported by {self._descriptor.component_id}')
+        normalized_payload = sdk_clone_object(payload, 'adapter request payload')
+        request_hash = canonical_request_sha256(self._descriptor, operation, normalized_payload)
+        try:
+            raw = handler(sdk_clone_object(normalized_payload, 'adapter request payload'))
+        except ComponentSdkError:
+            raise
+        except Exception as error:
+            raise AdapterInvocationError(f'builtin adapter {self._descriptor.component_id} failed') from error
+        output = sdk_json_object(raw, 'adapter response')
+        encoded = canonical_json_bytes(output)
+        previous = self._observed.get(request_hash)
+        if previous is not None and previous != encoded:
+            raise AdapterInvocationError(f'builtin adapter {self._descriptor.component_id} is nondeterministic')
+        self._observed[request_hash] = encoded
+        decoded: Any = json.loads(encoded)
+        return cast('dict[str, JsonValue]', decoded)
+
+class RecordedAdapter:
+    """Read-only response table indexed by a content-bound canonical request hash."""
+    __slots__ = ('_descriptor', '_records')
+
+    def __init__(self, descriptor: AdapterDescriptor, records: Mapping[str, Mapping[str, object]]) -> None:
+        if descriptor.implementation_kind != 'recorded':
+            raise AdapterRegistrationError('RecordedAdapter requires a recorded implementation')
+        normalized: dict[str, bytes] = {}
+        artifact: dict[str, JsonValue] = {}
+        for request_hash, response in records.items():
+            if sdk_SHA256.fullmatch(request_hash) is None:
+                raise AdapterRegistrationError('recorded request keys must be SHA-256 digests')
+            value = sdk_json_object(response, f'recorded response {request_hash}')
+            normalized[request_hash] = canonical_json_bytes(value)
+            artifact[request_hash] = value
+        if not normalized:
+            raise AdapterRegistrationError('RecordedAdapter requires at least one response')
+        if json_sha256(artifact) != descriptor.implementation_artifact_sha256:
+            raise AdapterRegistrationError('recorded responses do not match the declared implementation artifact hash')
+        self._descriptor = descriptor
+        self._records = normalized
+
+    @property
+    def descriptor(self) -> AdapterDescriptor:
+        return self._descriptor
+
+    @property
+    def capabilities(self) -> tuple[EvaluationTarget, ...]:
+        return self._descriptor.capabilities
+
+    def invoke(self, operation: str, payload: Mapping[str, object]) -> dict[str, JsonValue]:
+        request_hash = canonical_request_sha256(self._descriptor, operation, payload)
+        encoded = self._records.get(request_hash)
+        if encoded is None:
+            raise AdapterInvocationError(f'recorded adapter {self._descriptor.component_id} has no matching request')
+        raw: Any = json.loads(encoded)
+        return cast('dict[str, JsonValue]', raw)
+
+class ComponentRegistry:
+    """Manifest-bound adapter registry with deterministic lookup and listing."""
+
+    def __init__(self, manifest: ComponentManifest) -> None:
+        self._manifest = manifest
+        for component in manifest.components:
+            if json_sha256(component.config) != component.config_sha256:
+                raise AdapterRegistrationError(f'component {component.component_id} config no longer matches its hash')
+        self._expected = {component.component_id: AdapterDescriptor.from_component(component) for component in manifest.components}
+        self._adapters: dict[str, ComponentAdapter] = {}
+
+    @property
+    def manifest(self) -> ComponentManifest:
+        return self._manifest
+
+    def register(self, adapter: ComponentAdapter) -> None:
+        descriptor = adapter.descriptor
+        expected = self._expected.get(descriptor.component_id)
+        if expected is None:
+            raise AdapterRegistrationError(f'adapter {descriptor.component_id} is absent from the component manifest')
+        if descriptor != expected:
+            raise AdapterRegistrationError(f'adapter {descriptor.component_id} descriptor differs from its manifest entry')
+        if adapter.capabilities != expected.capabilities:
+            raise AdapterRegistrationError(f'adapter {descriptor.component_id} capabilities differ from its descriptor')
+        if descriptor.component_id in self._adapters:
+            raise AdapterRegistrationError(f'adapter {descriptor.component_id} is already registered')
+        self._adapters[descriptor.component_id] = adapter
+
+    def resolve(self, component_id: str, target: EvaluationTarget, operation: str) -> ComponentAdapter:
+        adapter = self._adapters.get(component_id)
+        if adapter is None:
+            if component_id not in self._expected:
+                raise AdapterRegistrationError(f'component {component_id} is absent from the component manifest')
+            raise AdapterRegistrationError(f'component {component_id} has no registered adapter')
+        expected = self._expected[component_id]
+        component = self._manifest.by_id[component_id]
+        if json_sha256(component.config) != component.config_sha256:
+            raise AdapterRegistrationError(f'component {component_id} config no longer matches its hash')
+        if adapter.descriptor != expected or adapter.capabilities != expected.capabilities:
+            raise AdapterRegistrationError(f'registered adapter {component_id} descriptor drifted')
+        if target not in expected.capabilities:
+            raise AdapterRegistrationError(f'component {component_id} does not support {target.level}/{target.track}')
+        if operation not in expected.operations:
+            raise AdapterRegistrationError(f'component {component_id} does not support operation {operation!r}')
+        return adapter
+
+    def list(self) -> tuple[AdapterDescriptor, ...]:
+        """Return registered descriptors in stable component-ID order."""
+        return tuple((self._adapters[component_id].descriptor for component_id in sorted(self._adapters)))
+
+def sdk_text(value: object, context: str) -> str:
+    if not isinstance(value, str):
+        raise AdapterInvocationError(f'{context} must be text')
+    return value
+
+def sdk_number(value: object, context: str) -> float:
+    if isinstance(value, bool) or not isinstance(value, int | float):
+        raise AdapterInvocationError(f'{context} must be numeric')
+    result = float(value)
+    if not math.isfinite(result):
+        raise AdapterInvocationError(f'{context} must be finite')
+    return result
+
+def sdk_integer_config(component: ComponentSpec, key: str, default: int) -> int:
+    value = component.config.get(key, default)
+    if isinstance(value, bool) or not isinstance(value, int) or value < 1:
+        raise AdapterRegistrationError(f'{component.component_id} config.{key} must be positive')
+    return value
+
+def sdk_number_config(component: ComponentSpec, key: str, default: float) -> float:
+    value = component.config.get(key, default)
+    return sdk_number(value, f'{component.component_id} config.{key}')
+
+def sdk_rows(payload: Mapping[str, object], key: str) -> list[dict[str, JsonValue]]:
+    value = payload.get(key)
+    if not isinstance(value, list):
+        raise AdapterInvocationError(f'payload.{key} must be an array')
+    rows: list[dict[str, JsonValue]] = []
+    for index, row in enumerate(value):
+        rows.append(sdk_json_object(row, f'payload.{key}[{index}]'))
+    return rows
+
+def sdk_candidate_id(row: Mapping[str, object], index: int) -> str:
+    value = row.get('candidate_id', row.get('chunk_id', f'candidate-{index:04d}'))
+    return sdk_text(value, f'candidate[{index}].candidate_id')
+
+def sdk_candidate_text(row: Mapping[str, object], index: int) -> str:
+    value = row.get('contextualized_text', row.get('input', row.get('text')))
+    return sdk_text(value, f'candidate[{index}].text')
+
+def sdk_tokens(text: str) -> frozenset[str]:
+    return frozenset(sdk_TOKEN.findall(text.lower()))
+
+def sdk_lexical_score(query: str, text: str) -> float:
+    query_tokens = sdk_tokens(query)
+    if not query_tokens:
+        return 0.0
+    return len(query_tokens & sdk_tokens(text)) / len(query_tokens)
+
+def sdk_synthetic_chunker(component: ComponentSpec) -> AdapterHandler:
+    chunk_size = sdk_integer_config(component, 'chunk_size', 256)
+    raw_overlap = component.config.get('overlap', 0)
+    if isinstance(raw_overlap, bool) or not isinstance(raw_overlap, int):
+        raise AdapterRegistrationError(f'{component.component_id} config.overlap must be an integer')
+    if raw_overlap < 0 or raw_overlap >= chunk_size:
+        raise AdapterRegistrationError(f'{component.component_id} config.overlap must be in [0, chunk_size)')
+    step = chunk_size - raw_overlap
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        documents = sdk_rows(cast('Mapping[str, object]', payload), 'documents')
+        chunks: list[dict[str, JsonValue]] = []
+        for document_index, document in enumerate(documents):
+            document_id = sdk_text(document.get('document_id'), f'documents[{document_index}].document_id')
+            text = sdk_text(document.get('text'), f'documents[{document_index}].text')
+            for chunk_index, start in enumerate(range(0, len(text), step)):
+                end = min(start + chunk_size, len(text))
+                chunk_id = f'{document_id}:chunk:{chunk_index:04d}'
+                chunk_text = text[start:end]
+                chunks.append({'candidate_id': chunk_id, 'chunk_id': chunk_id, 'document_id': document_id, 'end': end, 'input': chunk_text, 'start': start, 'text': chunk_text})
+                if end == len(text):
+                    break
+        return {'chunks': chunks}
+    return invoke
+
+def sdk_synthetic_embedder(component: ComponentSpec) -> AdapterHandler:
+    dimensions = sdk_integer_config(component, 'dimensions', 4)
+    if dimensions > 32:
+        raise AdapterRegistrationError(f'{component.component_id} config.dimensions must not exceed 32')
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        items = sdk_rows(cast('Mapping[str, object]', payload), 'items')
+        embeddings: list[dict[str, JsonValue]] = []
+        for index, item in enumerate(items):
+            item_id = sdk_candidate_id(cast('Mapping[str, object]', item), index)
+            text = sdk_candidate_text(cast('Mapping[str, object]', item), index)
+            digest = hashlib.sha256(text.encode('utf-8')).digest()
+            values = [digest[position] / 127.5 - 1.0 for position in range(dimensions)]
+            norm = math.sqrt(sum((value * value for value in values))) or 1.0
+            vector: list[JsonValue] = [round(value / norm, 12) for value in values]
+            embeddings.append({'candidate_id': item_id, 'vector': vector})
+        return {'embeddings': embeddings}
+    return invoke
+
+def sdk_synthetic_ranker(component: ComponentSpec, *, reranker: bool) -> AdapterHandler:
+    reverse = component.config.get('reverse', False)
+    if not isinstance(reverse, bool):
+        raise AdapterRegistrationError(f'{component.component_id} config.reverse must be boolean')
+    score_field = 'reranker_score' if reranker else 'dense_score'
+    rank_field = 'reranker_rank' if reranker else 'dense_rank'
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        query = sdk_text(payload.get('query'), 'payload.query')
+        candidates = sdk_rows(cast('Mapping[str, object]', payload), 'candidates')
+        scored: list[tuple[float, str, dict[str, JsonValue]]] = []
+        for index, candidate in enumerate(candidates):
+            identity = sdk_candidate_id(cast('Mapping[str, object]', candidate), index)
+            text = sdk_candidate_text(cast('Mapping[str, object]', candidate), index)
+            score = sdk_lexical_score(query, text)
+            if reverse:
+                score = 1.0 - score
+            scored.append((score, identity, dict(candidate)))
+        scored.sort(key=lambda item: (-item[0], item[1]))
+        result: list[dict[str, JsonValue]] = []
+        for rank, (score, _, candidate) in enumerate(scored, start=1):
+            candidate[score_field] = score
+            candidate[rank_field] = rank
+            result.append(candidate)
+        return {'candidates': result}
+    return invoke
+
+def sdk_synthetic_fusion(component: ComponentSpec) -> AdapterHandler:
+    dense_weight = sdk_number_config(component, 'dense_weight', 0.45)
+    reranker_weight = sdk_number_config(component, 'reranker_weight', 0.55)
+    if dense_weight < 0 or reranker_weight < 0 or dense_weight + reranker_weight <= 0:
+        raise AdapterRegistrationError(f'{component.component_id} fusion weights are invalid')
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        candidates = sdk_rows(cast('Mapping[str, object]', payload), 'candidates')
+        scored: list[tuple[float, str, dict[str, JsonValue]]] = []
+        for index, candidate in enumerate(candidates):
+            identity = sdk_candidate_id(cast('Mapping[str, object]', candidate), index)
+            dense = sdk_number(candidate.get('dense_score'), f'candidate[{index}].dense_score')
+            reranker_score = sdk_number(candidate.get('reranker_score'), f'candidate[{index}].reranker_score')
+            score = dense_weight * dense + reranker_weight * reranker_score
+            scored.append((score, identity, dict(candidate)))
+        scored.sort(key=lambda item: (-item[0], item[1]))
+        result: list[dict[str, JsonValue]] = []
+        for rank, (score, _, candidate) in enumerate(scored, start=1):
+            candidate['fusion_score'] = score
+            candidate['fusion_rank'] = rank
+            result.append(candidate)
+        return {'candidates': result}
+    return invoke
+
+def sdk_synthetic_dedup(_: ComponentSpec) -> AdapterHandler:
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        candidates = sdk_rows(cast('Mapping[str, object]', payload), 'candidates')
+        seen: set[str] = set()
+        next_rank = 1
+        result: list[dict[str, JsonValue]] = []
+        for index, candidate in enumerate(candidates):
+            passage = sdk_candidate_text(cast('Mapping[str, object]', candidate), index)
+            row = dict(candidate)
+            if passage in seen:
+                row['dedup_decision'] = 'drop'
+                row['post_dedup_rank'] = None
+            else:
+                seen.add(passage)
+                row['dedup_decision'] = 'keep'
+                row['post_dedup_rank'] = next_rank
+                next_rank += 1
+            result.append(row)
+        return {'candidates': result}
+    return invoke
+
+def sdk_synthetic_gate(component: ComponentSpec) -> AdapterHandler:
+    threshold = sdk_number_config(component, 'threshold', 0.0)
+    top_k = sdk_integer_config(component, 'top_k', 5)
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        candidates = sdk_rows(cast('Mapping[str, object]', payload), 'candidates')
+        next_rank = 1
+        selected: list[str] = []
+        result: list[dict[str, JsonValue]] = []
+        for index, candidate in enumerate(candidates):
+            row = dict(candidate)
+            kept = row.get('dedup_decision', 'keep') == 'keep'
+            raw_score = row.get('fusion_score', row.get('reranker_score', row.get('score', 0.0)))
+            score = sdk_number(raw_score, f'candidate[{index}].gate_score')
+            passed = kept and score >= threshold
+            row['gate_decision'] = 'pass' if passed else 'reject'
+            row['gate_threshold'] = threshold
+            if passed and next_rank <= top_k:
+                identity = sdk_candidate_id(cast('Mapping[str, object]', row), index)
+                row['final_rank'] = next_rank
+                selected.append(identity)
+                next_rank += 1
+            else:
+                row['final_rank'] = None
+            result.append(row)
+        return {'candidates': result, 'selected_candidate_ids': selected}
+    return invoke
+
+def sdk_synthetic_router(component: ComponentSpec) -> AdapterHandler:
+    should_call = component.config.get('should_call_rag', True)
+    if not isinstance(should_call, bool):
+        raise AdapterRegistrationError(f'{component.component_id} config.should_call_rag must be boolean')
+
+    def invoke(_: dict[str, JsonValue]) -> Mapping[str, object]:
+        return {'should_call_rag': should_call}
+    return invoke
+
+def sdk_synthetic_rewriter(_: ComponentSpec) -> AdapterHandler:
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        query = sdk_text(payload.get('query'), 'payload.query')
+        return {'query': query, 'rewritten_query': ' '.join(query.split())}
+    return invoke
+
+def sdk_synthetic_generator(component: ComponentSpec) -> AdapterHandler:
+    prefix_value = component.config.get('answer_prefix', '')
+    prefix = sdk_text(prefix_value, f'{component.component_id} config.answer_prefix')
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        contexts = sdk_rows(cast('Mapping[str, object]', payload), 'contexts')
+        passages = [sdk_candidate_text(cast('Mapping[str, object]', context), index) for index, context in enumerate(contexts)]
+        answer = ' '.join((part for part in (prefix, *passages) if part)).strip()
+        return {'answer': answer, 'abstained': not passages}
+    return invoke
+
+def sdk_synthetic_full_rag(_: ComponentSpec) -> AdapterHandler:
+
+    def invoke(payload: dict[str, JsonValue]) -> Mapping[str, object]:
+        query = sdk_text(payload.get('query'), 'payload.query')
+        contexts = sdk_rows(cast('Mapping[str, object]', payload), 'contexts')
+        context_ids = [sdk_candidate_id(cast('Mapping[str, object]', context), index) for index, context in enumerate(contexts)]
+        answer = ' '.join((sdk_candidate_text(cast('Mapping[str, object]', context), index) for index, context in enumerate(contexts)))
+        return {'actual_should_call_rag': bool(contexts), 'answer': answer, 'citations': context_ids, 'handoff_candidate_ids': context_ids, 'retrieved_candidate_ids': context_ids, 'rewritten_query': query, 'uttered_query': query}
+    return invoke
+
+def sdk_synthetic_handler(component: ComponentSpec) -> AdapterHandler:
+    if component.kind == 'chunker':
+        return sdk_synthetic_chunker(component)
+    if component.kind == 'embedder':
+        return sdk_synthetic_embedder(component)
+    if component.kind == 'retriever':
+        return sdk_synthetic_ranker(component, reranker=False)
+    if component.kind == 'reranker':
+        return sdk_synthetic_ranker(component, reranker=True)
+    if component.kind == 'fusion':
+        return sdk_synthetic_fusion(component)
+    if component.kind == 'dedup':
+        return sdk_synthetic_dedup(component)
+    if component.kind == 'gate':
+        return sdk_synthetic_gate(component)
+    if component.kind == 'router':
+        return sdk_synthetic_router(component)
+    if component.kind == 'rewriter':
+        return sdk_synthetic_rewriter(component)
+    if component.kind == 'generator':
+        return sdk_synthetic_generator(component)
+    return sdk_synthetic_full_rag(component)
+
+def synthetic_implementation_sha256() -> str:
+    """Hash the exact source artifact implementing every built-in synthetic adapter."""
+    return hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
+
+def make_synthetic_adapter(component: ComponentSpec) -> FunctionAdapter:
+    """Create the deterministic, dependency-free built-in for one manifest component."""
+    expected_id = SYNTHETIC_IMPLEMENTATION_IDS[component.kind]
+    if component.implementation.implementation_id != expected_id:
+        raise AdapterRegistrationError(f'synthetic {component.kind} requires implementation ID {expected_id}')
+    if component.implementation.artifact_sha256 != synthetic_implementation_sha256():
+        raise AdapterRegistrationError(f'synthetic {component.kind} artifact hash does not match component_sdk.py')
+    descriptor = AdapterDescriptor.from_component(component)
+    operation = OPERATIONS_BY_KIND[component.kind][0]
+    return FunctionAdapter(descriptor, {operation: sdk_synthetic_handler(component)})
+
+def make_synthetic_pipeline_adapters(components: Sequence[ComponentSpec]) -> tuple[FunctionAdapter, ...]:
+    """Build a complete Level 2 synthetic adapter tuple in production stage order."""
+    by_kind = {component.kind: component for component in components}
+    if len(by_kind) != len(components):
+        raise AdapterRegistrationError('synthetic pipeline component kinds must be unique')
+    missing = [kind for kind in PIPELINE_COMPONENT_ORDER if kind not in by_kind]
+    if missing:
+        raise AdapterRegistrationError(f"synthetic pipeline is missing component kinds: {', '.join(missing)}")
+    target = EvaluationTarget('level2', 'pipeline')
+    result: list[FunctionAdapter] = []
+    for kind in PIPELINE_COMPONENT_ORDER:
+        component = by_kind[kind]
+        if target not in component.capabilities:
+            raise AdapterRegistrationError(f'component {component.component_id} lacks level2/pipeline capability')
+        result.append(make_synthetic_adapter(component))
+    return tuple(result)
+
+def make_synthetic_full_rag_adapter(component: ComponentSpec) -> FunctionAdapter:
+    """Build a dependency-free full-RAG subject fixture adapter."""
+    if component.kind != 'full_rag_subject':
+        raise AdapterRegistrationError('full-RAG factory requires a full_rag_subject component')
+    return make_synthetic_adapter(component)
+
+def make_synthetic_registry(manifest: ComponentManifest) -> ComponentRegistry:
+    """Register every builtin manifest entry; recorded/command entries stay explicit."""
+    registry = ComponentRegistry(manifest)
+    for component in manifest.components:
+        if component.implementation.kind == 'builtin':
+            registry.register(make_synthetic_adapter(component))
+    return registry
+
+# Strict file loaders are shared with capture reopening.
+def load_component_manifest(path):
+    from ._track_capture import strict_json
+    return validate_component_manifest(strict_json(Path(path).read_bytes()))
+
+
+def load_experiment_manifest(path, component_manifest):
+    from ._track_capture import strict_json
+    return validate_experiment_manifest(strict_json(Path(path).read_bytes()), component_manifest)
+
+"""Bounded JSON command adapter for explicitly trusted local RAG components.
+
+Command adapters execute trusted, pinned local processes.  This protocol bounds their
+wire I/O, root-process waits, and local I/O-thread cleanup.  OS-level network,
+filesystem, and descendant-process containment remains the caller/deployment boundary;
+use a job object, cgroup, or equivalent when commands are not fully trusted.  Default
+synthetic and recorded evaluation runs launch no processes.
+"""
+import hashlib
+import json
+import os
+import re
+import subprocess
+import threading
+import time
+from collections.abc import Mapping, Sequence
+from contextlib import suppress
+from dataclasses import dataclass, field
+from io import BufferedReader
+from pathlib import Path
+from typing import IO, Any, cast
+REQUEST_SCHEMA = 'sable.rag.component-command.request.v1'
+RESPONSE_SCHEMA = 'sable.rag.component-command.response.v1'
+MAX_REQUEST_BYTES = 8388608
+MAX_RESPONSE_BYTES = 33554432
+MAX_STDERR_BYTES = 65536
+MAX_STDERR_CHARS = 4096
+command_PIPE_CHUNK_BYTES = 65536
+command_TERMINATE_GRACE_SECONDS = 0.25
+command_KILL_GRACE_SECONDS = 0.25
+command_THREAD_JOIN_GRACE_SECONDS = 0.25
+command_ID = re.compile('[a-z0-9][a-z0-9._:-]{0,127}')
+command_SHA256 = re.compile('[0-9a-f]{64}')
+command_INTERPRETER = re.compile('(?:pythonw?|node|ruby|perl|php|bash|sh|pwsh|powershell|cmd|java|dotnet)(?:\\d+(?:\\.\\d+)*)?(?:\\.exe)?', re.IGNORECASE)
+command_INLINE_OR_DISCOVERY_ARGUMENTS = frozenset({'-c', '-e', '-m', '--eval', '--execute'})
+command_PATH_SUFFIXES = frozenset({'.bat', '.bin', '.cfg', '.cjs', '.cmd', '.com', '.dll', '.dylib', '.exe', '.ini', '.jar', '.js', '.json', '.mjs', '.onnx', '.php', '.pl', '.ps1', '.pt', '.pth', '.py', '.pyw', '.rb', '.safetensors', '.sh', '.so', '.toml', '.ts', '.tsx', '.yaml', '.yml'})
+
+class ComponentInfrastructureError(RuntimeError):
+    """A command/process failure that must never become a quality score."""
+
+    def __init__(self, code: str, message: str) -> None:
+        self.code = code
+        super().__init__(message)
+
+@dataclass
+class _Capture:
+    limit: int
+    data: bytearray = field(default_factory=bytearray)
+    overflow: bool = False
+    error: OSError | None = None
+
+@dataclass
+class _Write:
+    error: OSError | None = None
+
+def command_safe_environment() -> dict[str, str]:
+    allowed = ('COMSPEC', 'LANG', 'PATH', 'PATHEXT', 'SYSTEMROOT', 'TEMP', 'TMP', 'WINDIR')
+    environment = {name: os.environ[name] for name in allowed if name in os.environ}
+    environment['PYTHONIOENCODING'] = 'utf-8'
+    return environment
+
+def command_normalize(value: object, context: str) -> JsonValue:
+    try:
+        encoded = canonical_json_bytes(cast('JsonValue', value))
+        loaded: Any = json.loads(encoded)
+    except (TypeError, ValueError) as error:
+        raise ComponentInfrastructureError('invalid_payload', f'{context} must contain finite JSON values') from error
+    return cast('JsonValue', loaded)
+
+def command_looks_like_relative_path(argument: str) -> bool:
+    path = Path(argument)
+    return bool(path.drive or '/' in argument or '\\' in argument or (path.suffix.lower() in command_PATH_SUFFIXES))
+
+def normalize_component_command(command: Sequence[str]) -> tuple[str, ...]:
+    """Validate bounded argv without resolving executables or relative code at runtime."""
+    result = tuple(command)
+    if not result or len(result) > 32 or (not Path(result[0]).is_absolute()):
+        raise ComponentInfrastructureError('invalid_command', 'component command must be bounded absolute argv')
+    if any((not item or len(item) > 4096 or '\x00' in item for item in result)):
+        raise ComponentInfrastructureError('invalid_command', 'component argv item is invalid')
+    executable = Path(result[0])
+    if not executable.is_file():
+        raise ComponentInfrastructureError('invalid_command', 'component executable must be an existing absolute file')
+    if command_INTERPRETER.fullmatch(executable.name) and (len(result) < 2 or not Path(result[1]).is_absolute() or (not Path(result[1]).is_file())):
+        raise ComponentInfrastructureError('invalid_command', 'interpreter commands require an existing absolute script as argv[1]')
+    if any((argument in command_INLINE_OR_DISCOVERY_ARGUMENTS for argument in result[1:])):
+        raise ComponentInfrastructureError('invalid_command', 'inline code and module discovery command forms are forbidden')
+    for argument in result[1:]:
+        path = Path(argument)
+        if path.is_absolute() and (not path.is_file()):
+            raise ComponentInfrastructureError('invalid_command', 'absolute command path arguments must be existing files')
+        if not path.is_absolute() and command_looks_like_relative_path(argument):
+            raise ComponentInfrastructureError('invalid_command', 'relative command file and code paths are forbidden')
+    return result
+
+def command_read_bounded(stream: IO[bytes], capture: _Capture, changed: threading.Event) -> None:
+    """Drain one pipe while retaining no more than its configured byte limit."""
+    try:
+        while True:
+            read_size = min(command_PIPE_CHUNK_BYTES, capture.limit - len(capture.data) + 1)
+            chunk = stream.read1(read_size) if isinstance(stream, BufferedReader) else stream.read(read_size)
+            if not chunk:
+                return
+            remaining = capture.limit - len(capture.data)
+            if len(chunk) > remaining:
+                if remaining > 0:
+                    capture.data.extend(chunk[:remaining])
+                capture.overflow = True
+                changed.set()
+                return
+            capture.data.extend(chunk)
+    except OSError as error:
+        capture.error = error
+        changed.set()
+    finally:
+        with suppress(OSError):
+            stream.close()
+        changed.set()
+
+def command_write_request(stream: IO[bytes], wire: bytes, state: _Write, changed: threading.Event) -> None:
+    try:
+        stream.write(wire)
+        stream.flush()
+    except BrokenPipeError:
+        pass
+    except OSError as error:
+        state.error = error
+        changed.set()
+    finally:
+        with suppress(OSError):
+            stream.close()
+        changed.set()
+
+def command_wait_bounded(process: subprocess.Popen[bytes], timeout: float) -> bool:
+    try:
+        process.wait(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        return False
+    return True
+
+def command_terminate_and_reap(process: subprocess.Popen[bytes]) -> bool:
+    """Stop and reap a component using only explicitly bounded waits."""
+    if process.poll() is not None:
+        return command_wait_bounded(process, 0)
+    with suppress(OSError):
+        process.terminate()
+    if command_wait_bounded(process, command_TERMINATE_GRACE_SECONDS):
+        return True
+    with suppress(OSError):
+        process.kill()
+    return command_wait_bounded(process, command_KILL_GRACE_SECONDS)
+
+def command_join_threads_bounded(threads: Sequence[threading.Thread], timeout: float) -> bool:
+    deadline = time.monotonic() + timeout
+    for thread in threads:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            break
+        thread.join(timeout=remaining)
+    return all((not thread.is_alive() for thread in threads))
+
+def command_capture_process(argv: tuple[str, ...], wire: bytes, timeout_seconds: float) -> tuple[int, bytes, bytes]:
+    try:
+        executable = Path(argv[0])
+        working_directory = Path(argv[1]).parent if command_INTERPRETER.fullmatch(executable.name) else executable.parent
+        process = subprocess.Popen(argv, stdin=subprocess.PIPE, stdout=subprocess.PIPE, stderr=subprocess.PIPE, shell=False, close_fds=True, cwd=working_directory, env=command_safe_environment())
+    except OSError as error:
+        raise ComponentInfrastructureError('spawn_failed', f'could not start component: {error}') from error
+    if process.stdin is None or process.stdout is None or process.stderr is None:
+        command_terminate_and_reap(process)
+        raise ComponentInfrastructureError('spawn_failed', 'component pipes were not created')
+    changed = threading.Event()
+    stdout = _Capture(MAX_RESPONSE_BYTES)
+    stderr = _Capture(MAX_STDERR_BYTES)
+    writer = _Write()
+    threads = (threading.Thread(target=command_read_bounded, args=(process.stdout, stdout, changed), name='component-stdout', daemon=True), threading.Thread(target=command_read_bounded, args=(process.stderr, stderr, changed), name='component-stderr', daemon=True), threading.Thread(target=command_write_request, args=(process.stdin, wire, writer, changed), name='component-stdin', daemon=True))
+    started: list[threading.Thread] = []
+    try:
+        for thread in threads:
+            thread.start()
+            started.append(thread)
+    except RuntimeError as error:
+        reaped = command_terminate_and_reap(process)
+        joined = command_join_threads_bounded(started, command_THREAD_JOIN_GRACE_SECONDS)
+        cleanup = '' if reaped and joined else '; bounded cleanup was incomplete'
+        raise ComponentInfrastructureError('thread_start_failed', f'could not start component I/O thread{cleanup}') from error
+    deadline = time.monotonic() + timeout_seconds
+    failure: tuple[str, str] | None = None
+    while True:
+        if stdout.overflow:
+            failure = ('response_too_large', 'component response exceeds limit')
+            break
+        if stderr.overflow:
+            failure = ('stderr_too_large', 'component stderr exceeds limit')
+            break
+        if stdout.error is not None or stderr.error is not None or writer.error is not None:
+            failure = ('io_failed', 'component pipe I/O failed')
+            break
+        process_done = process.poll() is not None
+        io_done = all((not thread.is_alive() for thread in threads))
+        if process_done and io_done:
+            break
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            failure = ('timeout', f'component process or pipe I/O timed out after {timeout_seconds:g} seconds')
+            break
+        changed.wait(min(remaining, 0.05))
+        changed.clear()
+    if failure is not None:
+        reaped = command_terminate_and_reap(process)
+        joined = command_join_threads_bounded(threads, command_THREAD_JOIN_GRACE_SECONDS)
+        cleanup = '' if reaped and joined else '; bounded cleanup was incomplete'
+        raise ComponentInfrastructureError(failure[0], failure[1] + cleanup)
+    returncode = process.returncode
+    if returncode is None:
+        command_terminate_and_reap(process)
+        raise ComponentInfrastructureError('process_state', 'component exit state is unavailable')
+    if stdout.overflow:
+        raise ComponentInfrastructureError('response_too_large', 'component response exceeds limit')
+    if stderr.overflow:
+        raise ComponentInfrastructureError('stderr_too_large', 'component stderr exceeds limit')
+    io_error = stdout.error or stderr.error or writer.error
+    if io_error is not None:
+        raise ComponentInfrastructureError('io_failed', f'component pipe I/O failed: {io_error}') from io_error
+    return (returncode, bytes(stdout.data), bytes(stderr.data))
+
+def run_component_command(command: Sequence[str], *, component_id: str, component_sha256: str, operation: str, payload: Mapping[str, object], timeout_seconds: float) -> dict[str, JsonValue]:
+    """Invoke exactly one pinned component command without shell, discovery, or retry."""
+    argv = normalize_component_command(command)
+    if command_ID.fullmatch(component_id) is None or command_ID.fullmatch(operation) is None:
+        raise ComponentInfrastructureError('invalid_request', 'component or operation ID is invalid')
+    if command_SHA256.fullmatch(component_sha256) is None:
+        raise ComponentInfrastructureError('invalid_request', 'component SHA-256 is invalid')
+    if not 0 < timeout_seconds <= 3600:
+        raise ComponentInfrastructureError('invalid_timeout', 'timeout must be in (0, 3600]')
+    normalized = command_normalize(payload, 'payload')
+    if not isinstance(normalized, dict):
+        raise ComponentInfrastructureError('invalid_payload', 'payload must be an object')
+    request_id = hashlib.sha256(canonical_json_bytes({'component_id': component_id, 'component_sha256': component_sha256, 'operation': operation, 'payload': normalized})).hexdigest()
+    request: dict[str, JsonValue] = {'schema_version': REQUEST_SCHEMA, 'request_id': request_id, 'component_id': component_id, 'component_sha256': component_sha256, 'operation': operation, 'payload': normalized}
+    wire = canonical_json_bytes(request) + b'\n'
+    if len(wire) > MAX_REQUEST_BYTES:
+        raise ComponentInfrastructureError('request_too_large', 'component request exceeds limit')
+    returncode, stdout, stderr = command_capture_process(argv, wire, timeout_seconds)
+    if returncode != 0:
+        stderr_text = stderr.decode('utf-8', errors='replace').strip()[:MAX_STDERR_CHARS]
+        suffix = f': {stderr_text}' if stderr_text else ''
+        raise ComponentInfrastructureError('nonzero_exit', f'component exited {returncode}{suffix}')
+    try:
+        raw: Any = json.loads(stdout.decode('utf-8'), parse_constant=command_reject_constant)
+    except (UnicodeDecodeError, json.JSONDecodeError, ComponentInfrastructureError) as error:
+        raise ComponentInfrastructureError('malformed_json', f'component returned invalid JSON: {error}') from error
+    if not isinstance(raw, Mapping):
+        raise ComponentInfrastructureError('invalid_response', 'component response must be an object')
+    response = cast('Mapping[str, object]', raw)
+    required = {'schema_version', 'request_id', 'component_id', 'component_sha256', 'status', 'output', 'error'}
+    if response.keys() != required or response['schema_version'] != RESPONSE_SCHEMA:
+        raise ComponentInfrastructureError('invalid_response', 'component response contract differs')
+    for key, expected in {'request_id': request_id, 'component_id': component_id, 'component_sha256': component_sha256}.items():
+        if response[key] != expected:
+            raise ComponentInfrastructureError('identity_drift', f'component response changed {key}')
+    if response['status'] != 'ok' or response['error'] is not None:
+        raise ComponentInfrastructureError('component_error', f"component reported error: {response['error']}")
+    output = command_normalize(response['output'], 'response.output')
+    if not isinstance(output, dict):
+        raise ComponentInfrastructureError('invalid_response', 'component output must be an object')
+    return output
+
+def command_reject_constant(value: str) -> None:
+    raise ComponentInfrastructureError('malformed_json', f'non-finite JSON constant: {value}')
+
+"""Manifest-bound adapter for bounded local component commands."""
+import hashlib
+import os
+import stat
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import BinaryIO
+MAX_COMMAND_ARTIFACT_BYTES = 1073741824
+adapter_HASH_CHUNK_BYTES = 1048576
+
+def adapter_file_identity(stream: BinaryIO, path: Path) -> tuple[str, int]:
+    before = os.fstat(stream.fileno())
+    if not stat.S_ISREG(before.st_mode):
+        raise AdapterRegistrationError(f'command artifact is not a regular file: {path}')
+    if before.st_size > MAX_COMMAND_ARTIFACT_BYTES:
+        raise AdapterRegistrationError(f'command artifact exceeds byte limit: {path}')
+    digest = hashlib.sha256()
+    while (chunk := stream.read(adapter_HASH_CHUNK_BYTES)):
+        digest.update(chunk)
+    after = os.fstat(stream.fileno())
+    stable_fields = ('st_dev', 'st_ino', 'st_size', 'st_mtime_ns')
+    if any((getattr(before, field) != getattr(after, field) for field in stable_fields)):
+        raise AdapterRegistrationError(f'command artifact changed while hashing: {path}')
+    return (digest.hexdigest(), before.st_size)
+
+def command_artifact_sha256(command: Sequence[str]) -> str:
+    """Bind validated exact argv plus every absolute regular-file argument."""
+    try:
+        argv = normalize_component_command(command)
+    except ComponentInfrastructureError as error:
+        raise AdapterRegistrationError(str(error)) from error
+    entries: list[JsonValue] = []
+    for argument in argv:
+        path = Path(argument)
+        entry: dict[str, JsonValue] = {'argument': argument}
+        if path.is_absolute():
+            try:
+                with path.open('rb') as stream:
+                    file_sha256, size_bytes = adapter_file_identity(stream, path)
+            except OSError as error:
+                raise AdapterRegistrationError(f'cannot hash command artifact {path}') from error
+            entry['file_sha256'] = file_sha256
+            entry['size_bytes'] = size_bytes
+        entries.append(entry)
+    return json_sha256(entries)
+
+def adapter_component_identity_sha256(descriptor: AdapterDescriptor) -> str:
+    """Bind command requests to the complete runtime-visible component identity."""
+    value: dict[str, JsonValue] = {'capabilities': [{'level': capability.level, 'track': capability.track} for capability in descriptor.capabilities], 'component_id': descriptor.component_id, 'component_kind': descriptor.component_kind, 'component_version': descriptor.component_version, 'config_sha256': descriptor.config_sha256, 'implementation_artifact_sha256': descriptor.implementation_artifact_sha256, 'implementation_id': descriptor.implementation_id, 'implementation_kind': descriptor.implementation_kind, 'implementation_version': descriptor.implementation_version, 'implementation_argv': list(descriptor.implementation_argv), 'operations': list(descriptor.operations), 'resource_context': {'hardware': descriptor.resource_context.hardware, 'device': descriptor.resource_context.device, 'precision': descriptor.resource_context.precision, 'batch_size': descriptor.resource_context.batch_size, 'candidate_depth': descriptor.resource_context.candidate_depth, 'warmup_runs': descriptor.resource_context.warmup_runs, 'measurement_method': descriptor.resource_context.measurement_method, 'timeout_seconds': descriptor.resource_context.timeout_seconds}}
+    return hashlib.sha256(canonical_json_bytes(value)).hexdigest()
+
+class CommandAdapter:
+    """Invoke one explicitly pinned executable through the bounded JSON protocol."""
+    __slots__ = ('_argv', '_component_sha256', '_descriptor', '_timeout_seconds')
+
+    def __init__(self, component: ComponentSpec, *, timeout_seconds: float | None=None) -> None:
+        if component.implementation.kind != 'command':
+            raise AdapterRegistrationError('CommandAdapter requires a command implementation')
+        if not component.implementation.argv:
+            raise AdapterRegistrationError('CommandAdapter requires pinned absolute argv')
+        timeout = component.resource_context.timeout_seconds if timeout_seconds is None else timeout_seconds
+        if not 0 < timeout <= 3600:
+            raise AdapterRegistrationError('command timeout must be in (0, 3600]')
+        if timeout > component.resource_context.timeout_seconds:
+            raise AdapterRegistrationError(f'command timeout override cannot exceed the component manifest timeout ({component.resource_context.timeout_seconds:g} seconds)')
+        self._descriptor = AdapterDescriptor.from_component(component)
+        self._argv = component.implementation.argv
+        if command_artifact_sha256(self._argv) != component.implementation.artifact_sha256:
+            raise AdapterRegistrationError('command files and argv do not match the implementation artifact hash')
+        self._component_sha256 = adapter_component_identity_sha256(self._descriptor)
+        self._timeout_seconds = timeout
+
+    @property
+    def descriptor(self) -> AdapterDescriptor:
+        return self._descriptor
+
+    @property
+    def capabilities(self) -> tuple[EvaluationTarget, ...]:
+        return self._descriptor.capabilities
+
+    def invoke(self, operation: str, payload: Mapping[str, object]) -> dict[str, JsonValue]:
+        if operation not in self._descriptor.operations:
+            raise AdapterInvocationError(f'operation {operation!r} is not supported by {self._descriptor.component_id}')
+        try:
+            actual_artifact = command_artifact_sha256(self._argv)
+        except AdapterRegistrationError as error:
+            raise ComponentInfrastructureError('identity_drift', str(error)) from error
+        if actual_artifact != self._descriptor.implementation_artifact_sha256:
+            raise ComponentInfrastructureError('identity_drift', 'command files or argv changed after registration')
+        return run_component_command(self._argv, component_id=self._descriptor.component_id, component_sha256=self._component_sha256, operation=operation, payload=payload, timeout_seconds=self._timeout_seconds)
+
+def make_command_adapter(component: ComponentSpec, *, timeout_seconds: float | None=None) -> CommandAdapter:
+    """Create a command adapter without performing discovery or execution."""
+    return CommandAdapter(component, timeout_seconds=timeout_seconds)
+
+
+# Equivalent canonical names for the native RAG coordinator. These aliases do
+# not expand its execution scope or change any manifest field/schema/hash.
+# Keep aliases after the final loader definition so strict native parsing is
+# retained when a legacy definition is superseded within this module.
+BatchConfiguration = ExperimentConfiguration
+BatchAlternative = ExperimentAlternative
+BatchPlan = ExperimentManifest
+validate_batch_manifest = validate_experiment_manifest
+load_batch_manifest = load_experiment_manifest