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

sphynx/retrieval_candidates.py

@@ -0,0 +1,295 @@
+"""Portable seven-arm retrieval candidates with explicit signal provenance.
+
+The core is dependency free. Model backends are explicit caller-supplied objects;
+recorded signals never become fresh inference by running the assembly code.
+Reference labels are not accepted by candidate or signal contracts.
+"""
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from collections import defaultdict
+from collections.abc import Callable, Mapping, Sequence
+from dataclasses import dataclass
+from pathlib import Path
+from types import MappingProxyType
+from typing import Any
+
+from .contracts import ContractError, canonical_json
+from . import customer_rerank as _bm25_module
+from .integration_contracts import CandidateConfiguration, value_digest, _freeze
+from .retrieval import RETRIEVAL_PACK_ID, RETRIEVAL_INTERFACE_VERSION, RETRIEVAL_REQUEST_SCHEMA, RETRIEVAL_RESPONSE_SCHEMA, _response, _policy
+
+METHODS = ("bm25-only", "dense-a-only", "dense-b-only", "hybrid-a-rrf",
+           "hybrid-b-rrf", "hybrid-a-rrf-minilm", "hybrid-b-rrf-minilm")
+MODEL_PROFILES = MappingProxyType({key: MappingProxyType(value) for key, value in {
+    "embedding-a": {"checkpoint": "Snowflake/snowflake-arctic-embed-m-v2.0",
+                    "revision": "95c2741480856aa9666782eb4afe11959938017f", "query_prompt": "query: "},
+    "embedding-b": {"checkpoint": "Snowflake/snowflake-arctic-embed-m-v1.5",
+                    "revision": "e58a8f756156a1293d763f17e3aae643474e9b8a", "query_prompt": "Represent this sentence for searching relevant passages: "},
+    "reranker": {"checkpoint": "cross-encoder/ms-marco-MiniLM-L-6-v2",
+                 "revision": "233902d25c440f23af6f7d6e94d2946bac0bee0a"},
+}.items()})
+IMPLEMENTATION_DIGEST = "sha256:" + hashlib.sha256(Path(__file__).read_bytes()).hexdigest()
+BM25_IMPLEMENTATION_DIGEST = "sha256:" + hashlib.sha256(Path(_bm25_module.__file__).read_bytes()).hexdigest()
+
+
+def reciprocal_rank_fusion(branches: Sequence[Sequence[str]], *, k: int = 60) -> list[str]:
+    if type(k) is not int or k <= 0:
+        raise ContractError("RRF k must be a positive integer")
+    scores: dict[str, float] = defaultdict(float)
+    for branch in branches:
+        if len(branch) != len(set(branch)) or any(type(cid) is not str or not cid for cid in branch):
+            raise ContractError("RRF branches require unique nonempty chunk IDs")
+        for rank, cid in enumerate(branch, 1):
+            scores[cid] += 1.0 / (k + rank)
+    return sorted(scores, key=lambda cid: (-scores[cid], cid))
+
+
+def select_whole_chunk_context(ranked_ids: Sequence[str], corpus: Mapping[str, Mapping], *,
+                              max_context_bytes: int = 16000, top_k: int = 5) -> list[str]:
+    if type(max_context_bytes) is not int or max_context_bytes < 1 or type(top_k) is not int or top_k < 1:
+        raise ContractError("positive integer context limits required")
+    chosen: list[str] = []
+    used = 0
+    for cid in ranked_ids:
+        added = len(corpus[cid]["text"].encode("utf-8")) + (2 if chosen else 0)
+        if used + added <= max_context_bytes:
+            chosen.append(cid)
+            used += added
+        if len(chosen) == top_k:
+            break
+    return chosen
+
+
+def _copy(value: Any) -> Any:
+    def thaw(item):
+        if isinstance(item, Mapping):
+            return {key: thaw(child) for key, child in item.items()}
+        if isinstance(item, (tuple, list)):
+            return [thaw(child) for child in item]
+        return item
+    return json.loads(canonical_json(thaw(value)))
+
+
+def _request(request: Mapping[str, Any]) -> dict:
+    expected = {"schema_version", "pack_id", "interface_version", "query_id", "query", "customer",
+                "conversation_context", "corpus_digest", "execution_policy", "corpus", "request_sha256"}
+    if not isinstance(request, Mapping) or set(request) != expected:
+        raise ContractError("retrieval request must contain only the declared label-free fields")
+    copied = _copy(dict(request))
+    for name in ("query_id", "query", "customer", "corpus_digest"):
+        if type(copied[name]) is not str or not copied[name].strip() or "\x00" in copied[name]:
+            raise ContractError("retrieval request identities and question must be nonempty text")
+    if (copied["schema_version"] != RETRIEVAL_REQUEST_SCHEMA or copied["interface_version"] != RETRIEVAL_INTERFACE_VERSION
+            or copied["pack_id"] != RETRIEVAL_PACK_ID):
+        raise ContractError("retrieval interface mismatch")
+    if copied["request_sha256"] != value_digest({key: value for key, value in copied.items() if key != "request_sha256"}):
+        raise ContractError("retrieval request digest mismatch")
+    corpus = copied["corpus"]
+    if not isinstance(corpus, list) or not corpus:
+        raise ContractError("customer-scoped corpus is required")
+    fields = {"chunk_id", "document_id", "customer", "text", "text_sha256", "source_class", "source_uri"}
+    if any(not isinstance(chunk, dict) or set(chunk) != fields or
+           any(type(value) is not str or not value.strip() or "\x00" in value for value in chunk.values())
+           for chunk in corpus):
+        raise ContractError("corpus chunks must contain only declared label-free fields")
+    ids = [chunk.get("chunk_id") for chunk in corpus]
+    if any(type(cid) is not str or not cid for cid in ids) or len(ids) != len(set(ids)):
+        raise ContractError("corpus chunk IDs must be unique")
+    for chunk in corpus:
+        if chunk.get("customer") != copied["customer"]:
+            raise ContractError("cross-customer corpus is forbidden")
+        text = chunk.get("text")
+        if type(text) is not str or chunk.get("text_sha256", "").removeprefix("sha256:") != hashlib.sha256(text.encode()).hexdigest():
+            raise ContractError("corpus text hash mismatch")
+    policy = copied["execution_policy"]
+    if not isinstance(policy, dict) or canonical_json(policy) != canonical_json(_policy(policy.get("max_context_bytes"))):
+        raise ContractError("seven-arm execution policy differs from the declared policy")
+    return copied
+
+
+def _rank_ids(raw: Sequence[str], request: Mapping) -> list[str]:
+    if (not isinstance(raw, (list, tuple)) or any(type(cid) is not str for cid in raw)
+            or len(raw) != len(set(raw))):
+        raise ContractError("dense backend must return unique ranked IDs")
+    allowed = {chunk["chunk_id"] for chunk in request["corpus"]}
+    if len(raw) != min(50, len(allowed)) or any(cid not in allowed for cid in raw):
+        raise ContractError("dense backend requires complete top-50 customer-scoped output")
+    return list(raw)
+
+
+def _rank_scores(scores: Mapping, expected_ids: Sequence[str]) -> list[str]:
+    if not isinstance(scores, Mapping) or set(scores) != set(expected_ids):
+        raise ContractError("reranker must score exactly the fused candidate pool")
+    for value in scores.values():
+        if type(value) not in (int, float) or not math.isfinite(value):
+            raise ContractError("reranker scores must be finite numbers")
+    return sorted(expected_ids, key=lambda cid: (-scores[cid], cid))
+
+
+@dataclass(frozen=True)
+class RetrievalCandidate:
+    _identity_json: str
+    adapter: Callable[[dict], dict]
+    execution_mode: str
+
+    @property
+    def identity(self) -> dict:
+        return json.loads(self._identity_json)
+
+    def run(self, dataset_path, output_dir, **kwargs):
+        """Use existing SDK capture policy; replay has no inference latency."""
+        from .retrieval import capture_retrieval, load_retrieval_pack, build_retrieval_request, run_retrieval
+        if self.execution_mode == "recorded":
+            pack = load_retrieval_pack(dataset_path, expected_sha256=kwargs.get("expected_sha256"))
+            responses = [{"query_id": case["query_id"], "response": self.adapter(build_retrieval_request(
+                pack, case, max_context_bytes=kwargs.get("max_context_bytes", 16000)))} for case in pack.cases]
+            return capture_retrieval(self.identity, dataset_path, responses, output_dir, **kwargs)
+        return run_retrieval(self.identity, self.adapter, dataset_path, output_dir, **kwargs)
+
+
+class RecordedHybridSignals:
+    """Read only exact request-bound dense orders and previously inferred logits.
+
+    This archive contains no reference labels or complete candidate responses.
+    Fusion, ranking, context assembly and grading are executed again, while the
+    upstream neural signals retain their original recorded provenance.
+    """
+    def __init__(self, artifact: Mapping, *, expected_digest: str):
+        raw = _copy(dict(artifact))
+        if value_digest(raw) != expected_digest:
+            raise ContractError("recorded retrieval signal digest mismatch")
+        if set(raw) != {"schema_version", "source", "models", "requests"} or raw["schema_version"] != "sphynx.retrieval.recorded-signals.v1":
+            raise ContractError("invalid recorded signal archive")
+        if raw["models"] != _copy(MODEL_PROFILES):
+            raise ContractError("recorded model identities mismatch")
+        source_fields = {"dataset_digest", "corpus_digest", "cohort_digest", "experiment_digest", "generation_receipt_digest",
+                         "source_files", "model_snapshot_digests", "provenance", "limitations"}
+        if not isinstance(raw["source"], dict) or set(raw["source"]) - source_fields:
+            raise ContractError("unknown recorded provenance fields")
+        self._identity_json = canonical_json({"mode": "recorded", "artifact_digest": expected_digest,
+                         "models": _copy(raw["models"]), "source": _copy(raw["source"])})
+        rows = raw["requests"]
+        if not isinstance(rows, list) or not rows:
+            raise ContractError("recorded request inventory is empty")
+        self._rows = {}
+        for row in rows:
+            if set(row) != {"query_id", "request_sha256", "corpus_digest", "dense", "reranker"}:
+                raise ContractError("unknown recorded signal fields; reference labels are not permitted")
+            digest = row["request_sha256"]
+            if digest in self._rows or type(digest) is not str:
+                raise ContractError("duplicate recorded request identity")
+            self._rows[digest] = _freeze(row)
+        self._rows = MappingProxyType(self._rows)
+
+    @property
+    def identity(self):
+        return json.loads(self._identity_json)
+
+    def _row(self, request):
+        row = self._rows.get(request["request_sha256"])
+        if row is None or any(row[field] != request[field] for field in ("query_id", "corpus_digest")):
+            raise ContractError("recorded signals do not bind this exact request")
+        return row
+
+    def dense_rank(self, request, profile):
+        row = self._row(request)
+        if profile not in row["dense"]:
+            raise ContractError("recorded dense profile missing")
+        return list(row["dense"][profile])
+
+    def rerank_scores(self, request, profile, ids):
+        row = self._row(request)
+        if profile not in row["reranker"]:
+            raise ContractError("recorded reranker profile missing")
+        scores = row["reranker"][profile]
+        if set(scores) != set(ids):
+            raise ContractError("recorded fused pool differs; refusing partial or changed score replay")
+        return dict(scores)
+
+
+def make_retrieval_candidate(method: str, *, configuration: CandidateConfiguration, backend=None) -> RetrievalCandidate:
+    """Compose a portable algorithm; constructing it does not load any model."""
+    if method not in METHODS or not isinstance(configuration, CandidateConfiguration):
+        raise ContractError("unsupported retrieval method/configuration")
+    if configuration.interface_version != RETRIEVAL_INTERFACE_VERSION or configuration.source_digest != IMPLEMENTATION_DIGEST:
+        raise ContractError("retrieval configuration source/interface mismatch")
+    if configuration.execution_mode not in ("trusted_local", "recorded") or configuration.credential_refs:
+        raise ContractError("retrieval families accept explicit local or recorded backends, without credentials")
+    params = _copy(dict(configuration.parameters))
+    if set(params) != {"method", "rrf_k", "max_context_bytes", "models", "backend_identity"} or params["method"] != method:
+        raise ContractError("retrieval configuration must pin method, policy, models and backend identity")
+    if type(params["rrf_k"]) is not int or params["rrf_k"] <= 0 or type(params["max_context_bytes"]) is not int or params["max_context_bytes"] <= 0:
+        raise ContractError("positive integer retrieval limits required")
+    required = {} if method == "bm25-only" else {"embedding-a" if "-a-" in method else "embedding-b":
+                                               dict(MODEL_PROFILES["embedding-a" if "-a-" in method else "embedding-b"])}
+    if method.endswith("-minilm"):
+        required["reranker"] = dict(MODEL_PROFILES["reranker"])
+    if params["models"] != required:
+        raise ContractError("method model identities must match original pinned profiles")
+    if method == "bm25-only":
+        if backend is not None or configuration.execution_mode != "trusted_local" or params["backend_identity"] != {"mode": "fresh_bm25"}:
+            raise ContractError("BM25 is fresh deterministic execution and needs no model backend")
+    elif backend is None or params["backend_identity"] != _copy(dict(backend.identity)):
+        raise ContractError("backend identity does not match frozen configuration")
+    elif backend.identity.get("mode") != configuration.execution_mode:
+        raise ContractError("backend execution mode mismatch")
+    profile = "embedding-a" if "-a-" in method else "embedding-b"
+
+    def adapter(request):
+        if backend is not None and _copy(dict(backend.identity)) != params["backend_identity"]:
+            raise ContractError("backend identity changed after configuration was frozen")
+        checked = _request(request)
+        if checked["execution_policy"]["max_context_bytes"] != params["max_context_bytes"]:
+            raise ContractError("request context policy differs from candidate configuration")
+        corpus = {chunk["chunk_id"]: chunk for chunk in checked["corpus"]}
+        bm25 = None
+        if method == "bm25-only" or method.startswith("hybrid-"):
+            bm25 = [chunk["chunk_id"] for _, chunk in _bm25_module._rank(checked["query"], checked["corpus"])[:50]]
+        if method == "bm25-only":
+            pool = fused = bm25
+        else:
+            dense = _rank_ids(backend.dense_rank(checked, profile), checked)
+            if method.startswith("dense-"):
+                pool = fused = dense
+            else:
+                branches = [bm25[:25], dense[:25]]
+                pool = list(dict.fromkeys(branches[0] + branches[1]))
+                fused = reciprocal_rank_fusion(branches, k=params["rrf_k"])
+        ranked = _rank_scores(backend.rerank_scores(checked, profile, fused), fused) if method.endswith("-minilm") else list(fused)
+        context = select_whole_chunk_context(ranked, corpus, max_context_bytes=params["max_context_bytes"])
+        result = {"schema_version": RETRIEVAL_RESPONSE_SCHEMA,
+                  **{field: checked[field] for field in ("query_id", "request_sha256", "corpus_digest")},
+                  "stages": {"candidate": list(pool), "fused": list(fused), "reranked": ranked, "context": context}}
+        return _response(result, checked)
+
+    identity = {"name": method, "version": configuration.configuration_id,
+                "interface_version": RETRIEVAL_INTERFACE_VERSION,
+                "architecture": {"embedding": required or "none", "index": "exact_customer_scoped_top50.v1",
+                    "fusion": "equal_rrf_k=" + str(params["rrf_k"]) if method.startswith("hybrid-") else "none",
+                    "reranker": required.get("reranker", "none"), "chunking": "pinned_source_chunks",
+                    "context_selection": {"top_k": 5, "max_context_bytes": params["max_context_bytes"], "separator": "\n\n"},
+                    "code_revision": IMPLEMENTATION_DIGEST, "configuration_digest": configuration.digest,
+                    "bm25_implementation_digest": BM25_IMPLEMENTATION_DIGEST,
+                    "execution_mode": configuration.execution_mode, "backend_identity": params["backend_identity"]}}
+    return RetrievalCandidate(canonical_json(identity), adapter, configuration.execution_mode)
+
+
+def retrieval_configuration(method: str, *, backend=None, rrf_k: int = 60, max_context_bytes: int = 16000,
+                            configuration_id: str = "original-seven-arms-v1") -> CandidateConfiguration:
+    if method not in METHODS:
+        raise ContractError("unsupported retrieval method")
+    if method != "bm25-only" and backend is None:
+        raise ContractError("dense/hybrid retrieval requires an explicit pinned backend")
+    models = {}
+    if method != "bm25-only":
+        profile = "embedding-a" if "-a-" in method else "embedding-b"
+        models[profile] = dict(MODEL_PROFILES[profile])
+    if method.endswith("-minilm"):
+        models["reranker"] = dict(MODEL_PROFILES["reranker"])
+    return CandidateConfiguration(configuration_id=configuration_id, interface_version=RETRIEVAL_INTERFACE_VERSION,
+        source_digest=IMPLEMENTATION_DIGEST, execution_mode="trusted_local" if method == "bm25-only" else backend.identity["mode"],
+        parameters={"method": method, "rrf_k": rrf_k, "max_context_bytes": max_context_bytes,
+                    "models": models, "backend_identity": {"mode": "fresh_bm25"} if method == "bm25-only" else _copy(dict(backend.identity))})

sphynx/retrieval_catalog_data.py

@@ -0,0 +1,19 @@
+"""Content-free seven-arm retrieval discovery; optional backends are not loaded."""
+from .catalog import CandidateDescriptor
+
+_SOURCE = 'sha256:270118e6c0606a5f54942e6a940e11b3150aba7b71b689f0fb0670df50cf908c'
+_METHODS = ("bm25-only", "dense-a-only", "dense-b-only", "hybrid-a-rrf",
+            "hybrid-b-rrf", "hybrid-a-rrf-minilm", "hybrid-b-rrf-minilm")
+CANDIDATES = tuple(CandidateDescriptor(
+    candidate_id="retrieval-" + method + "-v1", track="retrieval",
+    interface_version="sphynx.rag.retrieve.v1", source_digest=_SOURCE,
+    supported_dataset_ids=("sable.hybrid100.retrieve.v1",),
+    execution_modes=("trusted_local",) if method == "bm25-only" else ("recorded", "trusted_local"),
+    implementation_status="available",
+    reason=("Dependency-free fresh BM25 available." if method == "bm25-only" else
+        "Assembly is available; recorded neural signals are verified. Fresh neural execution requires an explicit pinned offline backend and is not inferred from replay."),
+    local_prerequisites=("authorized exact customer-filtered corpus and dataset",) if method == "bm25-only" else
+        ("authorized exact corpus and dataset", "exact request-bound recorded signal archive or pinned caller-provided offline model backend",),
+    dependencies=(), model_identity_required=method != "bm25-only",
+    supported_python=("3.11", "3.12", "3.13", "3.14"),
+) for method in _METHODS)

sphynx/retrieval_recordings.py

@@ -0,0 +1,125 @@
+"""Explicit owner-side migration of sealed historical hybrid neural signals.
+
+Reads local input and original receipts; no model, provider or network access.
+The output contains request bindings, dense order and raw reranker scores only.
+It must stay outside a distributable wheel or candidate source PR.
+"""
+from __future__ import annotations
+import hashlib
+import json
+from pathlib import Path
+
+from .contracts import ContractError, canonical_json
+from .integration_contracts import require_digest, value_digest
+from .retrieval import build_retrieval_request, load_retrieval_pack
+from .retrieval_candidates import METHODS, MODEL_PROFILES, RecordedHybridSignals
+
+
+def _digest(path: Path) -> str:
+    h = hashlib.sha256()
+    with path.open("rb") as stream:
+        for block in iter(lambda: stream.read(1048576), b""):
+            h.update(block)
+    return "sha256:" + h.hexdigest()
+
+
+def import_hybrid_recordings(dataset_path, source_directory, output_path, *,
+                             expected_dataset_digest, expected_experiment_digest,
+                             expected_generation_receipt_digest=None):
+    """Freeze the complete source-bound signal archive without altering originals.
+
+    The initial historical run was sealed after execution, not at its start.
+    Preserve that limitation. No missing query vectors are synthesized.
+    """
+    root = Path(source_directory).resolve(strict=True)
+    dataset = Path(dataset_path).resolve(strict=True)
+    require_digest(expected_dataset_digest, "expected_dataset_digest")
+    require_digest(expected_experiment_digest, "expected_experiment_digest")
+    if _digest(root / "experiment.json") != expected_experiment_digest:
+        raise ContractError("historical experiment digest mismatch")
+    pack = load_retrieval_pack(dataset, expected_sha256=expected_dataset_digest)
+    experiment = json.loads((root / "experiment.json").read_bytes())
+    if experiment.get("schema_version") != "sphynx.hybrid.offline.experiment.v1" or experiment.get("arms") != list(METHODS):
+        raise ContractError("unsupported historical seven-arm generation")
+    if experiment["policy"]["dataset_sha256"] != expected_dataset_digest:
+        raise ContractError("historical source binds another dataset")
+    if experiment.get("case_count") != len(pack.cases) or experiment.get("chunk_count") != len(pack.corpus):
+        raise ContractError("historical generation inventory differs from the dataset")
+    receipt = None
+    hashes = experiment.get("artifact_hashes")
+    if hashes is None:
+        require_digest(expected_generation_receipt_digest, "expected_generation_receipt_digest")
+        path = root / "generation-receipt.json"
+        if _digest(path) != expected_generation_receipt_digest:
+            raise ContractError("historical generation receipt digest mismatch")
+        receipt = json.loads(path.read_bytes())
+        if (receipt.get("schema_version") != "sphynx.hybrid.generation-receipt.v1"
+                or receipt.get("experiment_sha256") != expected_experiment_digest
+                or receipt.get("post_generation_dataset_sha256") != expected_dataset_digest
+                or receipt.get("generation_tool_sha256") != experiment["policy"]["code_sha256"]):
+            raise ContractError("historical receipt does not bind source and dataset")
+        hashes = receipt.get("artifact_hashes")
+    if not isinstance(hashes, dict) or not hashes:
+        raise ContractError("historical source inventory is missing")
+    required = {method + "-stages.json" for method in METHODS} | {"reranker-scores.json"}
+    if not required <= set(hashes):
+        raise ContractError("historical source has incomplete stage/score coverage")
+    for name, expected in hashes.items():
+        require_digest(expected, "historical artifact digest")
+        if not isinstance(name, str) or Path(name).name != name or name in ("experiment.json", "generation-receipt.json"):
+            raise ContractError("historical archive path is invalid")
+        path = (root / name).resolve(strict=True)
+        if path.parent != root or _digest(path) != expected:
+            raise ContractError("historical archive artifact changed")
+    generation_name = receipt["generation_source_name"] if receipt else experiment["policy"].get("generation_source_name")
+    if generation_name not in hashes or hashes[generation_name] != experiment["policy"]["code_sha256"]:
+        raise ContractError("original generation source is not bound")
+    for profile, spec in MODEL_PROFILES.items():
+        recorded = experiment["models"].get(profile)
+        if not isinstance(recorded, dict) or any(recorded.get(k) != v for k, v in spec.items()):
+            raise ContractError("historical model profile mismatch")
+    stage_rows = {}
+    query_ids = {case["query_id"] for case in pack.cases}
+    for method in METHODS:
+        value = json.loads((root / (method + "-stages.json")).read_bytes())
+        if set(value) != {"arm_id", "cases"} or value["arm_id"] != method or set(value["cases"]) != query_ids:
+            raise ContractError("historical arm has incomplete or foreign cases")
+        stage_rows[method] = value["cases"]
+    raw_scores = json.loads((root / "reranker-scores.json").read_bytes())
+    scores = {}
+    for method in ("hybrid-a-rrf-minilm", "hybrid-b-rrf-minilm"):
+        rows = raw_scores.get(method)
+        if not isinstance(rows, list) or len(rows) != len(query_ids):
+            raise ContractError("historical model score inventory is incomplete")
+        scores[method] = {row["query_id"]: row["scores"] for row in rows if set(row) == {"query_id", "scores"}}
+        if len(scores[method]) != len(rows) or set(scores[method]) != query_ids:
+            raise ContractError("historical model scores contain duplicates or unknown cases")
+    requests = []
+    for case in pack.cases:
+        request = build_retrieval_request(pack, case, max_context_bytes=experiment["policy"]["max_context_bytes"])
+        rows = {"query_id": request["query_id"], "request_sha256": request["request_sha256"],
+                "corpus_digest": request["corpus_digest"],
+                "dense": {profile: stage_rows[method][case["query_id"]]["candidate"]
+                          for profile, method in (("embedding-a", "dense-a-only"), ("embedding-b", "dense-b-only"))},
+                "reranker": {profile: scores[method][case["query_id"]]
+                             for profile, method in (("embedding-a", "hybrid-a-rrf-minilm"), ("embedding-b", "hybrid-b-rrf-minilm"))}}
+        requests.append(rows)
+    artifact = {"schema_version": "sphynx.retrieval.recorded-signals.v1",
+                "models": {profile: dict(value) for profile, value in MODEL_PROFILES.items()},
+                "requests": requests,
+                "source": {"dataset_digest": pack.dataset_digest, "corpus_digest": pack.corpus_digest,
+                    "cohort_digest": pack.cohort_digest, "experiment_digest": expected_experiment_digest,
+                    "generation_receipt_digest": expected_generation_receipt_digest,
+                    "source_files": hashes,
+                    "model_snapshot_digests": {key: value["snapshot_digest"] for key, value in experiment["models"].items()},
+                    "provenance": receipt.get("provenance") if receipt else "generation_bound_artifacts",
+                    "limitations": [receipt["dataset_attestation_scope"], receipt["bm25_dependency_attestation_scope"]] if receipt else []}}
+    digest = value_digest(artifact)
+    RecordedHybridSignals(artifact, expected_digest=digest)
+    target = Path(output_path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    with target.open("x", encoding="utf-8") as stream:
+        stream.write(canonical_json(artifact) + "\n")
+    return {"path": str(target), "artifact_digest": digest, "file_digest": _digest(target),
+            "case_count": len(requests), "execution_mode": "recorded", "model_inference": False,
+            "source_provenance": artifact["source"]["provenance"], "limitations": artifact["source"]["limitations"]}