agentinputlab 0.1.0a1__py3-none-any.whl

agentinputlab/algorithms/acquire/ircot_native.py

@@ -0,0 +1,355 @@
+"""Full native IRCoT-QA, with source-locked and explicit dependency substitutions."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from collections.abc import Mapping
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+from agentinputlab.artifacts import load_pinned_json_mapping
+from agentinputlab.contracts import (
+    AlgorithmOutputError,
+    ArtifactError,
+    BudgetExceededError,
+    CapabilityError,
+    CompositeResult,
+    ContextBlock,
+    ExecutionTrace,
+    ExternalDependencyError,
+    FrozenAgentState,
+    InterventionContext,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+)
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping, to_jsonable
+from agentinputlab.integrations.external_workers.ircot import (
+    IRCOT_UPSTREAM_COMMIT,
+    IRCoTControls,
+    IRCoTWorkerRequest,
+    IRCoTWorkerResponse,
+)
+
+IRCOT_NATIVE_QA_RELEASE = "acquire.ircot.native_like_substituted"
+IRCOT_NATIVE_QA_BINDING_MODE = "agentinputlab.ircot.native_like_qa.v1"
+IRCOT_NATIVE_QA_MANIFEST_SCHEMA = "agentinputlab.ircot.native_like_substitutions.v1"
+_ROLES = {
+    "retrieve_and_reset_paragraphs",
+    "step_by_step_cot_gen",
+    "step_by_step_exit_controller",
+    "copy_question",
+    "llmqa",
+    "answer_extractor",
+}
+
+
+def _manifest(fingerprint):
+    if (
+        not isinstance(fingerprint, Mapping)
+        or fingerprint.get("binding_mode") != IRCOT_NATIVE_QA_BINDING_MODE
+        or fingerprint.get("upstream_commit") != IRCOT_UPSTREAM_COMMIT
+        or fingerprint.get("full_six_participant_QA_graph") is not True
+        or fingerprint.get("native_final_prediction_extraction") is not True
+    ):
+        raise ArtifactError("IRCoT native-like profile requires the complete pinned QA runtime")
+    for key in ("generator", "retriever", "tokenizer", "native_dependencies"):
+        if not isinstance(fingerprint.get(key), Mapping) or not fingerprint[key]:
+            raise ArtifactError("IRCoT native-like runtime dependency fingerprints are incomplete")
+    for key in ("corpus_revision", "index_revision", "prompt_sha256"):
+        if not isinstance(fingerprint.get(key), str) or not fingerprint[key].strip():
+            raise ArtifactError("IRCoT native-like source identities are incomplete")
+    for key in (
+        "max_model_calls",
+        "max_output_tokens",
+        "max_retrieval_calls",
+        "per_call_output_tokens",
+    ):
+        if type(fingerprint.get(key)) is not int or fingerprint[key] < 1:
+            raise ArtifactError("IRCoT native-like runtime budgets must be positive integers")
+    if type(fingerprint.get("seed")) is not int or fingerprint["seed"] < 0:
+        raise ArtifactError("IRCoT native-like runtime seed must be a nonnegative integer")
+    return dict(
+        schema=IRCOT_NATIVE_QA_MANIFEST_SCHEMA,
+        release_id=IRCOT_NATIVE_QA_RELEASE,
+        runtime_fingerprint=to_jsonable(fingerprint),
+        runtime_fingerprint_sha256=content_hash(fingerprint),
+        substitutions=[
+            "generation_backend",
+            "retrieval_backend_and_index",
+            "gpt2_tokenizer_resolver",
+        ],
+        original_controller_and_six_participants=True,
+        native_answer_extraction=True,
+        original_native_generator_default_cap=300,
+        per_call_limit_is_a_ceiling_not_an_increase=True,
+        shared_final_call_and_output_budget=True,
+        original_cache_or_retry=False,
+        historical_Codex_full_Elasticsearch_or_published_score_parity=False,
+    )
+
+
+def write_ircot_substitution_manifest(runtime, output, *, accept_substitutions=False):
+    """Create-only operator acceptance of the exact native-like dependency set."""
+    if accept_substitutions is not True:
+        raise ArtifactError(
+            "review the IRCoT model/index substitutions and acknowledge them explicitly"
+        )
+    value = _manifest(runtime.fingerprint())
+    path = Path(output).expanduser().absolute()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    with path.open("x") as f:
+        json.dump(value, f, indent=2, sort_keys=True, allow_nan=False)
+    return dict(path=str(path), sha256=hashlib.sha256(path.read_bytes()).hexdigest())
+
+
+@dataclass(frozen=True, slots=True)
+class IRCoTNativeQARequest:
+    legacy: IRCoTWorkerRequest
+    max_model_calls: int
+    per_call_output_tokens: int
+    seed: int
+    expected_runtime_fingerprint_sha256: str
+
+    def external_reservation(self):
+        return {"model_calls": 1, "retrieval_calls": 1}
+
+    def raise_for_external_status(self, result):
+        if not isinstance(result, Mapping) or result.get("status") != "ok":
+            code = (
+                result.get("failure_code", "INVALID_RESPONSE")
+                if isinstance(result, Mapping)
+                else "INVALID_RESPONSE"
+            )
+            if code == "NATIVE_QA_EMPTY_OR_NON_TEXT":
+                raise AlgorithmOutputError(
+                    "native IRCoT-QA preserved an empty/non-text final prediction"
+                )
+            raise ExternalDependencyError(f"native IRCoT-QA failed with {code}")
+
+
+@dataclass(frozen=True, slots=True)
+class IRCoTNativeLikeSubstituted:
+    manifest_path: str | Path
+    expected_manifest_sha256: str
+    controls: IRCoTControls | Mapping = field(
+        default_factory=lambda: IRCoTControls(
+            per_step_top_k=6, max_steps=7, max_total_documents=15, max_output_tokens=4096
+        )
+    )
+    method_id: str = "ircot"
+    release_id: str = IRCOT_NATIVE_QA_RELEASE
+    family: SemanticFamily = SemanticFamily.ACQUIRE
+    _binding: Mapping = field(init=False, repr=False)
+
+    def __post_init__(self):
+        if isinstance(self.controls, Mapping):
+            try:
+                object.__setattr__(self, "controls", IRCoTControls(**self.controls))
+            except (TypeError, ValueError) as exc:
+                raise ArtifactError("IRCoT full QA control fields are invalid") from exc
+        if not isinstance(self.controls, IRCoTControls):
+            raise ArtifactError("IRCoT full QA requires explicit controls")
+        for key in ("per_step_top_k", "max_steps", "max_total_documents", "max_output_tokens"):
+            if type(getattr(self.controls, key)) is not int or getattr(self.controls, key) < 1:
+                raise ArtifactError("IRCoT full QA controls must be positive integers")
+        if self.controls.deduplicate is not True:
+            raise ArtifactError("the pinned native IRCoT source always deduplicates")
+        if (
+            self.method_id != "ircot"
+            or self.release_id != IRCOT_NATIVE_QA_RELEASE
+            or self.family is not SemanticFamily.ACQUIRE
+        ):
+            raise ArtifactError("IRCoT full QA registered profile identity differs")
+        value = load_pinned_json_mapping(
+            self.manifest_path, expected_sha256=self.expected_manifest_sha256
+        )
+        if value != _manifest(value.get("runtime_fingerprint")):
+            raise ArtifactError(
+                "IRCoT full QA substitution manifest differs from the exact supported protocol"
+            )
+        object.__setattr__(self, "_binding", freeze_mapping(value))
+
+    def run(self, state: FrozenAgentState, context: InterventionContext) -> CompositeResult:
+        if not state.query.strip() or not state.task_id:
+            raise CapabilityError("IRCoT full QA requires question text and an explicit task ID")
+        if state.context or state.messages or state.tool_names or state.instruction:
+            raise CapabilityError(
+                "IRCoT full QA accepts question-only state plus an explicitly bound external corpus"
+            )
+        binding = load_pinned_json_mapping(
+            self.manifest_path, expected_sha256=self.expected_manifest_sha256
+        )
+        if content_hash(binding) != content_hash(self._binding):
+            raise ArtifactError("IRCoT full QA substitution manifest changed")
+        runtime = context.external_runtime
+        if (
+            runtime is None
+            or not callable(getattr(runtime, "run", None))
+            or not callable(getattr(runtime, "fingerprint", None))
+        ):
+            raise ExternalDependencyError(
+                "IRCoT full QA requires the startup-bound native QA runtime"
+            )
+        fingerprint = runtime.fingerprint()
+        if content_hash(fingerprint) != binding["runtime_fingerprint_sha256"]:
+            raise ArtifactError("IRCoT full QA exact runtime/model/index fingerprint mismatch")
+        for component, key in ((context.backend, "generator"), (context.retriever, "retriever")):
+            if component is None or not callable(getattr(component, "fingerprint", None)):
+                raise ExternalDependencyError(
+                    "IRCoT full QA requires backend and retriever fingerprints"
+                )
+            if content_hash(component.fingerprint()) != content_hash(fingerprint[key]):
+                raise ArtifactError(
+                    "IRCoT full QA context is not the acknowledged model/index substitution"
+                )
+        controls = self.controls
+        if (
+            context.seed != fingerprint["seed"]
+            or controls.max_steps + 1 > state.budget.max_model_calls
+            or controls.max_steps + 1 > fingerprint["max_model_calls"]
+            or controls.max_output_tokens
+            > min(state.budget.max_output_tokens, fingerprint["max_output_tokens"])
+            or controls.max_steps + 1
+            > min(state.budget.max_retrieval_calls, fingerprint["max_retrieval_calls"])
+        ):
+            raise BudgetExceededError(
+                "IRCoT full QA cannot reserve its declared reasoning/final workflow under the bound budget/seed"
+            )
+        base = dict(
+            state_hash=state.state_hash,
+            task_id=state.task_id,
+            question=state.query,
+            controls=asdict(controls),
+            generator_fingerprint=fingerprint["generator"],
+            retriever_fingerprint=fingerprint["retriever"],
+            corpus_revision=fingerprint["corpus_revision"],
+            index_revision=fingerprint["index_revision"],
+            prompt_hash=fingerprint["prompt_sha256"],
+        )
+        legacy = IRCoTWorkerRequest(
+            request_id=content_hash(
+                dict(
+                    base,
+                    release_id=self.release_id,
+                    manifest_sha256=self.expected_manifest_sha256,
+                    seed=context.seed,
+                )
+            ),
+            **{**base, "controls": controls},
+        )
+        request = IRCoTNativeQARequest(
+            legacy,
+            min(state.budget.max_model_calls, fingerprint["max_model_calls"]),
+            fingerprint["per_call_output_tokens"],
+            context.seed,
+            content_hash(fingerprint),
+        )
+        raw = runtime.run(request)
+        request.raise_for_external_status(raw)
+        if raw.get("identity") != fingerprint or content_hash(
+            runtime.fingerprint()
+        ) != content_hash(fingerprint):
+            raise ArtifactError("IRCoT full QA response/runtime identity changed")
+        response = IRCoTWorkerResponse.from_mapping(raw, request=legacy)
+        roles = [e["role"] for e in raw["native_controller_events"]]
+        # The original CopyQuestion participant schedules a task. After answer
+        # extraction the source controller visits it again to drain that task;
+        # its eoq_after_n_calls=1 guard ends without another model generation.
+        tail = ["copy_question", "llmqa", "answer_extractor", "copy_question"]
+        prefix = roles[:-4]
+        loop = [
+            "retrieve_and_reset_paragraphs",
+            "step_by_step_cot_gen",
+            "step_by_step_exit_controller",
+        ]
+        if (
+            not set(roles) >= _ROLES
+            or roles[-4:] != tail
+            or not prefix
+            or len(prefix) % 3
+            or any(prefix[i : i + 3] != loop for i in range(0, len(prefix), 3))
+        ):
+            raise AlgorithmOutputError(
+                "IRCoT full QA did not execute the complete native final-answer graph"
+            )
+        if (
+            not response.answer.strip()
+            or response.usage["model_calls"] > request.max_model_calls
+            or response.usage["model_calls"] != roles.count("step_by_step_cot_gen") + 1
+        ):
+            raise AlgorithmOutputError(
+                "IRCoT full QA answer/model accounting differs from its native graph"
+            )
+        by_id = {d.document_id: d for d in response.documents}
+        evidence = tuple(
+            ContextBlock(
+                text=by_id[i].text,
+                block_id=i,
+                source=response.documents[0].corpus_revision,
+                score=by_id[i].score,
+                metadata={
+                    "title": by_id[i].title,
+                    "corpus_revision": by_id[i].corpus_revision,
+                    "evidence_kind": "real_corpus_document",
+                },
+            )
+            for i in response.active_document_ids
+        )
+        return CompositeResult(
+            method_id=self.method_id,
+            release_id=self.release_id,
+            source_state_hash=state.state_hash,
+            final_answer=response.answer,
+            evidence=evidence,
+            trace=ExecutionTrace(
+                method_id=self.method_id,
+                release_id=self.release_id,
+                events=(
+                    TraceEvent(TracePhase.PREPARE, "native_qa_substitution_binding", binding),
+                    TraceEvent(
+                        TracePhase.OBSERVE,
+                        "native_qa_controller",
+                        {
+                            "events": raw["native_controller_events"],
+                            "model_classes": raw["native_model_classes"],
+                            "runtime_events": raw["controlled_runtime_events"],
+                        },
+                    ),
+                    TraceEvent(
+                        TracePhase.FINALIZE,
+                        "native_qa_prediction",
+                        {
+                            "answer": response.answer,
+                            "exit_reason": response.exit_reason,
+                            "active_document_ids": response.active_document_ids,
+                            "native_chain": raw["native_chain"],
+                        },
+                    ),
+                ),
+                counters=dict(response.usage),
+            ),
+            implementation_identity=IRCOT_NATIVE_QA_BINDING_MODE,
+            profile_kind="controlled_adapter",
+            metadata={
+                "substitution_manifest_sha256": self.expected_manifest_sha256,
+                "runtime_fingerprint": fingerprint,
+                "native_full_QA_graph_executed": True,
+                "native_final_prediction_extraction": True,
+                "independent_downstream_answer_call_added": False,
+                "native_generator_default_output_cap": 300,
+                "current_provider_usage_is_measured": raw["usage_is_complete"],
+                "original_historical_backbone_index_or_published_score_parity": False,
+                "automatic_retry": False,
+                "official_scoring": "caller_owned_independent_scorer",
+            },
+        )
+
+
+__all__ = [
+    "IRCOT_NATIVE_QA_RELEASE",
+    "IRCoTNativeLikeSubstituted",
+    "IRCoTNativeQARequest",
+    "write_ircot_substitution_manifest",
+]

agentinputlab/algorithms/acquire/ircot_replay.py

@@ -0,0 +1,327 @@
+"""Checksum-bound replay of original IRCoT ID-to-answer prediction files.
+
+The archive remains operator-owned. Loading verifies bytes and declared input/
+model bindings, not authorship or published-score parity. No prediction is
+passed off as corpus evidence and no model request is made during replay.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from pathlib import Path, PurePosixPath
+from typing import Any
+
+from agentinputlab.artifacts import load_pinned_json_mapping
+from agentinputlab.contracts import (
+    AlgorithmOutputError,
+    ArtifactError,
+    CompositeResult,
+    ExecutionTrace,
+    FrozenAgentState,
+    InterventionContext,
+    SemanticFamily,
+    TraceEvent,
+    TracePhase,
+    ValidationError,
+)
+from agentinputlab.contracts.serialization import content_hash, freeze_mapping
+
+IRCOT_REPLAY_RELEASE = "acquire.ircot.prediction_replay"
+IRCOT_REPLAY_SCHEMA = "agentinputlab.ircot.prediction_replay.v1"
+
+
+def _sha(value, label):
+    if (
+        not isinstance(value, str)
+        or len(value) != 64
+        or any(c not in "0123456789abcdef" for c in value)
+    ):
+        raise ArtifactError(f"IRCoT replay {label} must be a lowercase SHA-256")
+    return value
+
+
+def _mounted_json(root, spec):
+    if not isinstance(spec, Mapping) or set(spec) != {"path", "sha256"}:
+        raise ArtifactError("IRCoT replay files require a relative path and trusted checksum")
+    name = spec["path"]
+    if not isinstance(name, str) or not name or "\\" in name:
+        raise ArtifactError("IRCoT replay file path is invalid")
+    path = PurePosixPath(name)
+    if path.is_absolute() or ".." in path.parts or not path.parts:
+        raise ArtifactError("IRCoT replay file path must remain under its manifest directory")
+    target = root.joinpath(*path.parts)
+    if not target.parent.resolve().is_relative_to(root):
+        raise ArtifactError("IRCoT replay file parent escapes its manifest directory")
+    return load_pinned_json_mapping(
+        target, expected_sha256=_sha(spec["sha256"], "file checksum"), max_bytes=8 * 1024 * 1024
+    )
+
+
+@dataclass(frozen=True, slots=True)
+class IRCoTPredictionArchive:
+    """Immutable selected scope, including empty predictions and historical cost."""
+
+    manifest_sha256: str
+    manifest: Mapping[str, Any]
+    records: Mapping[str, Any]
+    source_prediction_count: int
+
+    def __post_init__(self):
+        object.__setattr__(self, "manifest", freeze_mapping(self.manifest))
+        object.__setattr__(self, "records", freeze_mapping(self.records))
+
+    @property
+    def generator_fingerprint_sha256(self):
+        return content_hash(self.manifest["generator_fingerprint"])
+
+
+def load_ircot_prediction_archive(manifest_path, *, expected_sha256):
+    """Load a bounded operator manifest plus an unchanged upstream-format file.
+
+    ``inputs`` is a label-free binding map, never a ground-truth answer file.
+    It may select a documented ID-based scope from a larger prediction file.
+    Unselected predictions remain counted in ``source_prediction_count``.
+    """
+    pin = _sha(expected_sha256, "manifest checksum")
+    path = Path(manifest_path).expanduser().absolute()
+    manifest = load_pinned_json_mapping(path, expected_sha256=pin, max_bytes=1024 * 1024)
+    required = {
+        "schema",
+        "origin_kind",
+        "run_revision",
+        "benchmark",
+        "split",
+        "generator_fingerprint",
+        "dependency_fingerprint",
+        "provenance",
+        "selection_rule",
+        "predictions",
+        "inputs",
+    }
+    if set(manifest) != required or manifest["schema"] != IRCOT_REPLAY_SCHEMA:
+        raise ArtifactError("IRCoT replay manifest schema/fields differ")
+    if manifest["origin_kind"] not in ("author_release", "controlled_capture"):
+        raise ArtifactError(
+            "IRCoT replay origin must be an author release or separately labelled controlled capture"
+        )
+    revision = manifest["run_revision"]
+    if (
+        not isinstance(revision, str)
+        or len(revision) != 40
+        or any(c not in "0123456789abcdef" for c in revision)
+    ):
+        raise ArtifactError(
+            "IRCoT replay run_revision must be the actual full immutable Git revision"
+        )
+    for key in ("benchmark", "split", "selection_rule"):
+        if not isinstance(manifest[key], str) or not manifest[key].strip():
+            raise ArtifactError(f"IRCoT replay requires {key}")
+    for key in ("generator_fingerprint", "dependency_fingerprint"):
+        if not isinstance(manifest[key], Mapping) or not manifest[key]:
+            raise ArtifactError(f"IRCoT replay requires {key}")
+        content_hash(manifest[key])
+    provenance = manifest["provenance"]
+    if not isinstance(provenance, Mapping) or set(provenance) != {
+        "source_uri",
+        "source_artifact_sha256",
+        "run_config_sha256",
+        "query_source_sha256",
+    }:
+        raise ArtifactError(
+            "IRCoT replay requires explicit source, configuration and query provenance"
+        )
+    if not isinstance(provenance["source_uri"], str) or not provenance["source_uri"].strip():
+        raise ArtifactError("IRCoT replay source_uri is required")
+    for key in ("source_artifact_sha256", "run_config_sha256", "query_source_sha256"):
+        _sha(provenance[key], key)
+    root = path.parent.resolve()
+    predictions = _mounted_json(root, manifest["predictions"])
+    bindings = _mounted_json(root, manifest["inputs"])
+    if not predictions or not bindings or not set(bindings) <= set(predictions):
+        raise ArtifactError("IRCoT replay selected IDs must exist in the original prediction file")
+    if any(
+        not isinstance(k, str) or not k or not isinstance(v, str) for k, v in predictions.items()
+    ):
+        raise ArtifactError(
+            "IRCoT answer replay requires the original ID-to-text format, not retrieval IDs or gold answer lists"
+        )
+    records = {}
+    for key, binding in bindings.items():
+        if not isinstance(binding, Mapping) or set(binding) != {
+            "query",
+            "input_state_hash",
+            "historical_usage",
+            "origin_receipt_sha256",
+        }:
+            raise ArtifactError("IRCoT replay input binding fields differ; labels are not allowed")
+        if not isinstance(binding["query"], str) or not binding["query"].strip():
+            raise ArtifactError("IRCoT replay input binding requires its exact source query")
+        for name in ("input_state_hash", "origin_receipt_sha256"):
+            if binding[name] is not None:
+                _sha(binding[name], name)
+        historical = binding["historical_usage"]
+        if historical is not None:
+            if not isinstance(historical, Mapping) or not historical:
+                raise ArtifactError(
+                    "IRCoT replay historical_usage must be measured data or null, never a guessed zero"
+                )
+            from agentinputlab.observability import normalize_external_usage
+
+            normalize_external_usage(historical)
+        if (
+            manifest["origin_kind"] == "controlled_capture"
+            and binding["origin_receipt_sha256"] is None
+        ):
+            raise ArtifactError(
+                "IRCoT controlled capture requires the original inference receipt checksum"
+            )
+        records[key] = {
+            **dict(binding),
+            "answer": predictions[key],
+            "status": "archived_prediction"
+            if predictions[key].strip()
+            else "archived_empty_prediction",
+        }
+    return IRCoTPredictionArchive(pin, manifest, records, len(predictions))
+
+
+@dataclass(frozen=True, slots=True)
+class IRCoTPredictionReplay:
+    manifest_path: str | Path
+    expected_manifest_sha256: str
+    expected_generator_fingerprint_sha256: str
+    benchmark: str
+    split: str
+    method_id: str = "ircot"
+    release_id: str = IRCOT_REPLAY_RELEASE
+    family: SemanticFamily = SemanticFamily.ACQUIRE
+    _archive: IRCoTPredictionArchive = field(init=False, repr=False)
+
+    def __post_init__(self):
+        if (
+            self.method_id != "ircot"
+            or self.release_id != IRCOT_REPLAY_RELEASE
+            or self.family is not SemanticFamily.ACQUIRE
+        ):
+            raise ValidationError("IRCoT replay identity differs from the registered profile")
+        archive = load_ircot_prediction_archive(
+            self.manifest_path, expected_sha256=self.expected_manifest_sha256
+        )
+        if archive.generator_fingerprint_sha256 != _sha(
+            self.expected_generator_fingerprint_sha256, "expected generator"
+        ):
+            raise ArtifactError("IRCoT replay belongs to a different model/deployment")
+        if (
+            archive.manifest["benchmark"] != self.benchmark
+            or archive.manifest["split"] != self.split
+        ):
+            raise ArtifactError("IRCoT replay benchmark/split does not match the requested scope")
+        object.__setattr__(self, "_archive", archive)
+
+    @property
+    def archive(self):
+        """Inspect original empty outcomes/provenance without fabricating answers."""
+        return self._archive
+
+    def run(self, state: FrozenAgentState, context: InterventionContext) -> CompositeResult:
+        # Recheck trusted files before reuse; there is never a live fallback.
+        archive = load_ircot_prediction_archive(
+            self.manifest_path, expected_sha256=self.expected_manifest_sha256
+        )
+        if archive != self._archive:
+            raise ArtifactError("IRCoT replay archive changed after construction")
+        record = archive.records.get(state.task_id)
+        if record is None or record["query"] != state.query:
+            raise ArtifactError("IRCoT replay exact task ID/query mismatch; no generation fallback")
+        if (
+            record["input_state_hash"] is not None
+            and record["input_state_hash"] != state.state_hash
+        ):
+            raise ArtifactError("IRCoT replay original input-state hash differs")
+        for key, value in (("benchmark_cell", self.benchmark), ("source_split", self.split)):
+            if key in state.metadata and state.metadata[key] != value:
+                raise ArtifactError("IRCoT replay visible dataset scope differs")
+        if (
+            context.backend is not None
+            and content_hash(context.backend.fingerprint()) != archive.generator_fingerprint_sha256
+        ):
+            raise ArtifactError(
+                "IRCoT replay cannot relabel an archived answer as another live backbone"
+            )
+        if not record["answer"].strip():
+            raise AlgorithmOutputError(
+                "IRCoT archived empty prediction preserved; no retry or replacement answer"
+            )
+        manifest = archive.manifest
+        return CompositeResult(
+            method_id=self.method_id,
+            release_id=self.release_id,
+            source_state_hash=state.state_hash,
+            final_answer=record["answer"],
+            evidence=(),
+            trace=ExecutionTrace(
+                method_id=self.method_id,
+                release_id=self.release_id,
+                events=(
+                    TraceEvent(
+                        TracePhase.PREPARE,
+                        "prediction_archive_binding",
+                        {
+                            "manifest_sha256": archive.manifest_sha256,
+                            "source_prediction_count": archive.source_prediction_count,
+                            "selected_record_count": len(archive.records),
+                            "task_id": state.task_id,
+                            "generator_fingerprint_sha256": archive.generator_fingerprint_sha256,
+                        },
+                    ),
+                    TraceEvent(
+                        TracePhase.FINALIZE,
+                        "archived_prediction",
+                        {
+                            "answer": record["answer"],
+                            "origin_receipt_sha256": record["origin_receipt_sha256"],
+                            "historical_usage": record["historical_usage"],
+                        },
+                    ),
+                ),
+                counters={
+                    "model_calls": 0,
+                    "retrieval_calls": 0,
+                    "input_tokens": 0,
+                    "output_tokens": 0,
+                },
+            ),
+            implementation_identity=IRCOT_REPLAY_SCHEMA,
+            profile_kind="official_native"
+            if manifest["origin_kind"] == "author_release"
+            else "controlled_adapter",
+            metadata={
+                "artifact_replay": True,
+                "origin_kind": manifest["origin_kind"],
+                "run_revision": manifest["run_revision"],
+                "manifest_sha256": archive.manifest_sha256,
+                "generator_fingerprint": manifest["generator_fingerprint"],
+                "dependency_fingerprint": manifest["dependency_fingerprint"],
+                "provenance": manifest["provenance"],
+                "historical_usage": record["historical_usage"],
+                "historical_cost_recharged": False,
+                "historical_usage_unknown": record["historical_usage"] is None,
+                "new_provider_requests": 0,
+                "current_seed_or_budget_rerun_claimed": False,
+                "input_state_hash_verified": record["input_state_hash"] is not None,
+                "answers_are_not_corpus_evidence": True,
+                "checksum_proves_authorship": False,
+                "benchmark_scoring": "caller_owned_independent_scorer",
+                "automatic_retry": False,
+            },
+        )
+
+
+__all__ = [
+    "IRCOT_REPLAY_RELEASE",
+    "IRCOT_REPLAY_SCHEMA",
+    "IRCoTPredictionArchive",
+    "IRCoTPredictionReplay",
+    "load_ircot_prediction_archive",
+]