agentinputlab 0.1.0a1__py3-none-any.whl

workers/official_arenas/retail_capture.py

@@ -0,0 +1,188 @@
+#!/usr/bin/env python3
+"""Approved, restart-safe Retail capture and partial-inventory projection.
+
+No real scope or authorization is manufactured here. Before enabling a scope,
+the operator must verify actual human scope and common-model choices. Successful
+captures become optimizer-visible inventories; capture failures remain in the
+full denominator, without invented checkpoints or automatic retries.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from types import SimpleNamespace
+from typing import Any
+
+if __package__ in {None, ""}:
+    sys.path[:0] = [str(Path(__file__).resolve().parents[2] / "src"),
+                   str(Path(__file__).resolve().parents[2])]
+
+from workers.official_arenas.capture_records import _records
+from agentinputlab.experiments.builders import CHECKPOINT_INVENTORY_PROTOCOL
+from workers.official_arenas.protocol import REPLAY_INVENTORY_PROTOCOL, OfficialArenaError, content_hash, sha256_file
+from workers.official_arenas.providers.tau_retail import SOURCE_REVISION, _create_only, _saved_capture, factory
+from workers.official_arenas.retail_driver import _read, _validate_authorizations
+
+PROTOCOL = "agentinputlab.retail-capture-scope.v1"
+_FIELDS = frozenset({"schema_version", "protocol", "source_revision", "phase", "execution_enabled",
+                    "output_root", "provider_config", "provider_config_sha256", "source_sha256",
+                    "authorizations", "expected_task_ids", "model_slot"})
+
+
+def _source_pins() -> dict[str, str]:
+    root = Path(__file__).resolve().parents[2]
+    return {relative: sha256_file(root / relative) for relative in (
+        "workers/official_arenas/retail_capture.py", "workers/official_arenas/retail_driver.py",
+        "workers/official_arenas/driver.py", "workers/official_arenas/protocol.py",
+        "workers/official_arenas/providers/tau_retail.py", "workers/official_arenas/providers/tau3.py",
+        "workers/official_arenas/capture_records.py",
+    )}
+
+
+def _validated_scope(path: Path, checksum: str, provider):
+    value = _read(path)
+    if sha256_file(path) != checksum or set(value) != _FIELDS:
+        raise OfficialArenaError("Retail capture scope fields or checksum differ")
+    if (type(value["schema_version"]) is not int or value["schema_version"] != 1
+            or value["protocol"] != PROTOCOL or value["source_revision"] != SOURCE_REVISION
+            or value["execution_enabled"] is not True or value["phase"] not in {"engineering", "formal"}):
+        raise OfficialArenaError("Retail capture scope is not enabled or valid")
+    _validate_authorizations(value["authorizations"])
+    parsed = provider._validate_config(value["provider_config"])
+    if value["provider_config_sha256"] != content_hash(parsed) or value["source_sha256"] != _source_pins():
+        raise OfficialArenaError("Retail capture source or effective config differs")
+    if parsed["task_split_name"] != ("train" if value["phase"] == "engineering" else "test"):
+        raise OfficialArenaError("Retail capture phase and official split differ")
+    ids = value["expected_task_ids"]
+    if (not isinstance(ids, list) or len(ids) != parsed["limit"]
+            or any(not isinstance(task_id, str) or not task_id.isdigit() for task_id in ids)
+            or len(ids) != len(set(ids))):
+        raise OfficialArenaError("Retail capture expected task inventory is invalid")
+    if not isinstance(value["model_slot"], str) or not value["model_slot"].strip():
+        raise OfficialArenaError("Retail capture model slot is absent")
+    root = Path(value["output_root"])
+    if (not root.is_absolute() or any(part.is_symlink() for part in (root, *root.parents))
+            or not root.is_dir() or root.stat().st_uid != os.getuid() or root.stat().st_mode & 0o077):
+        raise OfficialArenaError("Retail capture root must be an existing owned private directory")
+    return value, parsed, root
+
+
+def project_batch(provider, config: Mapping[str, Any], batch: Mapping[str, Any], *, root: Path,
+                  phase: str, model_slot: str, scope_sha256: str) -> Mapping[str, Any]:
+    """Read retained receipts, validate them, and export without generation."""
+    binding = content_hash(provider._validate_config(config))
+    ids, dispositions, captured = batch["expected_task_ids"], batch["dispositions"], batch["records"]
+    if (batch["protocol"] != "retail-capture-batch.v1" or batch["config_binding"] != binding
+            or len(ids) != len(set(ids)) or [row["task_id"] for row in dispositions] != ids
+            or any(row["status"] not in {"captured", "capture_failed", "reserved_unresolved"}
+                   or row["retry_permitted"] is not False for row in dispositions)):
+        raise OfficialArenaError("Retail capture dispositions differ from the expected inventory")
+    records_by_id = {row["checkpoint_id"]: row for row in captured}
+    if len(records_by_id) != len(captured):
+        raise OfficialArenaError("Retail capture repeats a checkpoint")
+    receipt_files = {}
+    for row in dispositions:
+        task_id = row["task_id"]
+        path = root / f"first-capture-{task_id}.json"
+        if row["status"] == "reserved_unresolved":
+            if task_id in records_by_id or path.exists() or path.is_symlink():
+                raise OfficialArenaError("Retail unresolved capture changed during projection")
+            start = root / f"first-capture-{task_id}-start.json"
+            _read(start)
+            receipt_files[start.name] = sha256_file(start)
+            continue
+        saved = _saved_capture(path, binding=binding, task_id=task_id)
+        if row["status"] != saved["terminal"] or row["receipt_sha256"] != saved["receipt_sha256"]:
+            raise OfficialArenaError("Retail capture terminal receipt differs")
+        receipt_files[path.name] = sha256_file(path)
+        if row["status"] == "captured":
+            if records_by_id.get(task_id) != saved["record"]:
+                raise OfficialArenaError("Retail projected checkpoint differs from its receipt")
+        elif task_id in records_by_id:
+            raise OfficialArenaError("Retail failed capture cannot have a fabricated checkpoint")
+    successful = [row["task_id"] for row in dispositions if row["status"] == "captured"]
+    if set(records_by_id) != set(successful):
+        raise OfficialArenaError("Retail captured checkpoint inventory differs")
+    terminal = all(row["status"] != "reserved_unresolved" for row in dispositions)
+    if batch["all_tasks_terminal"] is not terminal:
+        raise OfficialArenaError("Retail batch terminality differs")
+    output = {"protocol": "retail-capture-inventory-disposition.v1", "scope_sha256": scope_sha256,
+              "phase": phase, "benchmark_id": "tau3.retail", "source_revision": SOURCE_REVISION,
+              "model_slot": model_slot, "config_binding": binding, "expected_task_ids": ids,
+              "expected_denominator": len(ids), "captured_task_ids": successful,
+              "dispositions": dispositions, "all_tasks_terminal": terminal,
+              "retry_permitted": False, "receipt_files": receipt_files,
+              "failure_endpoints": "capture failures are unresolved environment outcomes, not invented agent zeros"}
+    artifacts = {}
+    if terminal and captured:
+        # Reuse only the existing projection/validation, never its capture or
+        # replacing writer. Protected simulator history stays in its own file.
+        proxy = SimpleNamespace(benchmark_id="tau3.retail", source_revision=SOURCE_REVISION,
+                                doctor=lambda _config: (), capture=lambda _config, **kwargs: captured)
+        visible, protected, units = _records(proxy, config, split=config["task_split_name"], output_root=root)
+        artifacts = {
+            "checkpoints.json": {"schema_version": 1, "protocol": CHECKPOINT_INVENTORY_PROTOCOL,
+                                 "checkpoint_count": len(visible), "checkpoints": visible},
+            "replays.json": {"schema_version": 1, "protocol": REPLAY_INVENTORY_PROTOCOL,
+                             "benchmark_id": "tau3.retail", "source_revision": SOURCE_REVISION,
+                             "record_count": len(protected), "records": protected},
+            "units.json": units,
+        }
+    output["inventory_content_sha256"] = {name: content_hash(value) for name, value in artifacts.items()}
+    snapshot = root / ("inventory-" + content_hash(output))
+    try:
+        snapshot.mkdir(mode=0o700)
+    except FileExistsError:
+        if snapshot.is_symlink() or _read(snapshot / "dispositions.json") != output:
+            raise OfficialArenaError("Retail inventory snapshot changed or is interrupted")
+        for name, value in artifacts.items():
+            path = snapshot / name
+            if path.is_symlink() or json.loads(path.read_bytes()) != value:
+                raise OfficialArenaError("Retail retained inventory artifact differs")
+        return {"snapshot": str(snapshot), "disposition": output}
+    for name, value in artifacts.items():
+        _create_only(snapshot / name, value)
+    _create_only(snapshot / "dispositions.json", output)
+    return {"snapshot": str(snapshot), "disposition": output}
+
+
+def run(path: Path, checksum: str) -> Mapping[str, Any]:
+    provider = factory()
+    scope, config, root = _validated_scope(path, checksum, provider)
+    blockers = provider.doctor(config)
+    if blockers:
+        raise OfficialArenaError("Retail native capture preflight did not pass")
+    from tau2.runner.helpers import get_tasks
+    ids = [str(task.id) for task in get_tasks("retail", task_split_name=config["task_split_name"], num_tasks=config["limit"])]
+    if ids != scope["expected_task_ids"]:
+        raise OfficialArenaError("Retail scoped official task order differs")
+    batch = provider.capture_batch(config, output_root=root)
+    return project_batch(provider, config, batch, root=root, phase=scope["phase"],
+                         model_slot=scope["model_slot"], scope_sha256=checksum)
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Run a bound first-attempt Retail capture batch")
+    parser.add_argument("--scope", type=Path, required=True)
+    parser.add_argument("--scope-sha256", required=True)
+    args = parser.parse_args()
+    try:
+        result = run(args.scope, args.scope_sha256)
+    except Exception as error:
+        print(json.dumps({"error": type(error).__name__, "message": "Retail capture rejected; inspect owned receipts"}), file=sys.stderr)
+        return 2
+    # No protected user history or visible request contents in the console.
+    disposition = result["disposition"]
+    print(json.dumps({"snapshot": result["snapshot"], "expected": disposition["expected_denominator"],
+                      "captured": len(disposition["captured_task_ids"]),
+                      "all_tasks_terminal": disposition["all_tasks_terminal"],
+                      "formal_inference_started": False}, sort_keys=True))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workers/official_arenas/retail_driver.py

@@ -0,0 +1,275 @@
+#!/usr/bin/env python3
+"""Durable, first-attempt-only Retail atomic worker.
+
+The original generic worker and historical providers are unchanged. This
+worker reuses their request/budget validators but never uses TemporaryDirectory.
+An operator must bind an immutable scope after verifying the actual human
+scope/environment choices; hash-shaped authorization references alone are not
+proof of consent. No enabled real scope is generated by this module.
+"""
+from __future__ import annotations
+
+import argparse
+import hashlib
+import json
+import os
+import re
+import sys
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Any
+
+if __package__ in {None, ""}:
+    sys.path.insert(0, str(Path(__file__).resolve().parents[2]))
+
+from workers.official_arenas import driver as shared
+from workers.official_arenas.protocol import (
+    OfficialArenaError, content_hash, intervention_usage, materialized_state,
+    merge_usage, resolve_shared_budget_config, sha256_file,
+)
+from workers.official_arenas.providers.tau_retail import SOURCE_REVISION, _create_only
+
+SCOPE_PATH_ENV = "AILAB_RETAIL_EXECUTION_SCOPE"
+SCOPE_SHA256_ENV = "AILAB_RETAIL_EXECUTION_SCOPE_SHA256"
+SCOPE_PROTOCOL = "agentinputlab.retail-execution-scope.v1"
+PROVIDER_ENTRYPOINT = "workers.official_arenas.providers.tau_retail:factory"
+_SHA = re.compile(r"^[0-9a-f]{64}$")
+_SCOPE_FIELDS = frozenset({"schema_version", "protocol", "source_revision", "phase", "execution_enabled",
+    "output_root", "provider_config_sha256", "provider_source_sha256", "worker_support_sha256",
+    "worker_source_sha256", "protocol_source_sha256", "provider_helper_sha256",
+    "authorizations", "allowed_cell_ids"})
+
+
+class RetailAttemptUnavailable(OfficialArenaError):
+    """Existing live/interrupted/unscored attempt must be inspected, not rerun."""
+
+
+def _reject_duplicate_keys(pairs):
+    result = {}
+    for key, value in pairs:
+        if key in result:
+            raise OfficialArenaError("Retail JSON has duplicate fields")
+        result[key] = value
+    return result
+
+
+def _read(path: Path) -> Mapping[str, Any]:
+    if path.is_symlink() or not path.is_file():
+        raise OfficialArenaError("Retail bound file is absent or symlinked")
+    try:
+        value = json.loads(path.read_bytes(), object_pairs_hook=_reject_duplicate_keys)
+        content_hash(value)  # also rejects non-finite numbers
+    except (ValueError, TypeError) as error:
+        raise OfficialArenaError("Retail bound file is invalid JSON") from error
+    if not isinstance(value, Mapping):
+        raise OfficialArenaError("Retail bound file must be an object")
+    return value
+
+
+def cell_identity(request: Mapping[str, Any]) -> Mapping[str, Any]:
+    """Logical cell identity excludes generated text, not method/budget/locks.
+
+    If a generated payload changes, its logical identity stays occupied and
+    its full request hash conflicts instead of silently becoming a new trial.
+    Different factors/intensities require their own frozen arm parameters.
+    """
+    arms = []
+    for arm in sorted(request["arms"], key=lambda item: item["role"]):
+        payload = arm["payload"]
+        arms.append({"role": arm["role"], "arm_id": arm["arm_id"],
+                     **{name: payload[name] for name in ("release_id", "profile_kind", "model_slot", "arm_parameters")},
+                     "budget": materialized_state(payload)["budget"]})
+    return {**{name: request[name] for name in ("benchmark_id", "checkpoint_id", "source_revision",
+                "origin_state_hash", "replay_identity", "seed", "locked_dependency_hashes")}, "arms": arms}
+
+
+def _validate_authorizations(approvals: Any) -> None:
+    # These are provenance references, not automatic verification of consent.
+    # The operator must verify the actual human messages before enabling a scope.
+    if not isinstance(approvals, Mapping) or set(approvals) != {"scope", "environment_models"}:
+        raise OfficialArenaError("Retail human choice references are incomplete")
+    for approval in approvals.values():
+        if (not isinstance(approval, Mapping) or set(approval) != {"source_kind", "thread_id", "message_sha256"}
+                or approval["source_kind"] != "human_message" or not isinstance(approval["thread_id"], str)
+                or not approval["thread_id"].strip() or not isinstance(approval["message_sha256"], str)
+                or _SHA.fullmatch(approval["message_sha256"]) is None):
+            raise OfficialArenaError("Retail human choice reference is invalid")
+
+
+def _scope(parameters: Mapping[str, Any], request: Mapping[str, Any]):
+    path_text, expected = os.environ.get(SCOPE_PATH_ENV), os.environ.get(SCOPE_SHA256_ENV)
+    if not path_text or not expected or _SHA.fullmatch(expected) is None:
+        raise OfficialArenaError("Retail requires an explicitly bound execution scope")
+    path = Path(path_text)
+    value = _read(path)
+    if sha256_file(path) != expected or set(value) != _SCOPE_FIELDS:
+        raise OfficialArenaError("Retail execution scope differs")
+    if (type(value["schema_version"]) is not int or value["schema_version"] != 1
+            or value["protocol"] != SCOPE_PROTOCOL or value["source_revision"] != SOURCE_REVISION
+            or value["phase"] not in {"engineering", "formal"} or value["execution_enabled"] is not True):
+        raise OfficialArenaError("Retail execution scope is not enabled or valid")
+    _validate_authorizations(value["authorizations"])
+    files = {"provider_source_sha256": Path(__file__).parent / "providers/tau_retail.py",
+             "worker_support_sha256": Path(shared.__file__), "worker_source_sha256": Path(__file__),
+             "protocol_source_sha256": Path(__file__).parent / "protocol.py",
+             "provider_helper_sha256": Path(__file__).parent / "providers/tau3.py"}
+    for name, source in files.items():
+        if source.is_symlink() or value[name] != sha256_file(source):
+            raise OfficialArenaError("Retail worker source closure differs")
+    config_hash = content_hash(resolve_shared_budget_config(parameters["provider_config"]))
+    if value["provider_config_sha256"] != config_hash:
+        raise OfficialArenaError("Retail frozen provider config differs")
+    allowed = value["allowed_cell_ids"]
+    if (not isinstance(allowed, list) or not allowed
+            or any(not isinstance(item, str) or _SHA.fullmatch(item) is None for item in allowed)
+            or len(allowed) != len(set(allowed))):
+        raise OfficialArenaError("Retail frozen cell inventory is invalid")
+    identity = cell_identity(request)
+    cell_id = content_hash(identity)
+    if cell_id not in allowed:
+        raise OfficialArenaError("Retail cell is outside its approved frozen inventory")
+    root = Path(value["output_root"])
+    if (not root.is_absolute() or any(part.is_symlink() for part in (root, *root.parents))
+            or not root.is_dir() or root.stat().st_uid != os.getuid() or root.stat().st_mode & 0o077):
+        raise OfficialArenaError("Retail ledger root must be an existing owned private directory")
+    return value, expected, root / cell_id, identity
+
+
+def _sealed(value: Mapping[str, Any]) -> dict[str, Any]:
+    return {**value, "receipt_sha256": content_hash(value)}
+
+
+def _files(root: Path) -> dict[str, str]:
+    result = {}
+    for path in sorted(root.rglob("*")):
+        if path.is_symlink():
+            raise OfficialArenaError("Retail attempt contains a symlink")
+        if path.is_file() and path != root / "terminal.json":
+            result[str(path.relative_to(root))] = sha256_file(path)
+    return result
+
+
+def _cached(root: Path, request_hash: str, scope_sha256: str):
+    if root.is_symlink() or not root.is_dir():
+        raise OfficialArenaError("Retail logical attempt directory is invalid")
+    start = _read(root / "pair-start.json")
+    if start.get("request_hash") != request_hash or start.get("scope_sha256") != scope_sha256:
+        raise OfficialArenaError("Retail existing logical cell has a different full request or scope")
+    if not (root / "terminal.json").exists():
+        raise RetailAttemptUnavailable("Retail attempt is live or interrupted; automatic retry is forbidden")
+    terminal = _read(root / "terminal.json")
+    body = {key: value for key, value in terminal.items() if key != "receipt_sha256"}
+    if (terminal.get("receipt_sha256") != content_hash(body) or terminal.get("request_hash") != request_hash
+            or terminal.get("scope_sha256") != scope_sha256 or terminal.get("files") != _files(root)):
+        raise OfficialArenaError("Retail terminal or raw trajectory evidence differs")
+    if terminal.get("status") != "paired_scored":
+        raise RetailAttemptUnavailable("Retail failed attempt is retained and terminal; automatic retry is forbidden")
+    response = _read(root / "response.json")
+    if content_hash(response) != terminal.get("response_sha256"):
+        raise OfficialArenaError("Retail retained response differs")
+    return response
+
+
+def run(value: Any) -> Mapping[str, Any]:
+    if not isinstance(value, Mapping) or set(value) != shared._ROOT_FIELDS:
+        raise OfficialArenaError("Retail atomic envelope fields differ")
+    if type(value["schema_version"]) is not int or value["schema_version"] != 1 or value["protocol"] != shared.REQUEST_PROTOCOL:
+        raise OfficialArenaError("Retail atomic envelope protocol differs")
+    base = {name: value[name] for name in shared._ROOT_FIELDS - {"request_hash"}}
+    if value["request_hash"] != content_hash(base):
+        raise OfficialArenaError("Retail full request hash differs")
+    parameters, request = shared._parameters(value["worker_parameters"]), shared._atomic_request(value["atomic_request"])
+    if (parameters["provider_entrypoint"] != PROVIDER_ENTRYPOINT or request["benchmark_id"] != "tau3.retail"
+            or request["source_revision"] != SOURCE_REVISION or request["seed"] != 17):
+        raise OfficialArenaError("Retail cannot run another provider, domain, source or seed")
+    records = shared._inventory(parameters)
+    replay = records.get(request["checkpoint_id"])
+    if (records["__inventory__"] != {"benchmark_id": "tau3.retail", "source_revision": SOURCE_REVISION}
+            or replay is None or any(replay[name] != request[name] for name in ("origin_state_hash", "replay_identity"))):
+        raise OfficialArenaError("Retail protected replay identity differs")
+    shared._validate_dependency_binding(request=request, parameters=parameters, replay_record=replay)
+    _, scope_sha, root, identity = _scope(parameters, request)
+    provider = shared._provider(PROVIDER_ENTRYPOINT)
+    if (provider.benchmark_id != request["benchmark_id"] or provider.source_revision != SOURCE_REVISION
+            or provider.scorer_id != parameters["scorer_id"] or provider.scorer_revision != parameters["scorer_revision"]):
+        raise OfficialArenaError("Retail provider identity differs from the worker lock")
+    blockers = provider.doctor(parameters["provider_config"])
+    if blockers:
+        raise OfficialArenaError("Retail native preflight did not pass")
+    try:
+        root.mkdir(mode=0o700)
+    except FileExistsError:
+        return _cached(root, value["request_hash"], scope_sha)
+    _create_only(root / "pair-start.json", {"request_hash": value["request_hash"], "scope_sha256": scope_sha,
+        "cell_identity": identity, "pid": os.getpid(), "uid": os.getuid(), "retry_permitted": False})
+    _create_only(root / "request.json", value)
+    results, receipts, failures, runtime_ids = [], [], [], set()
+    for arm in sorted(request["arms"], key=lambda item: item["role"]):
+        role, work = arm["role"], root / arm["role"]
+        work.mkdir(mode=0o700)
+        try:
+            result = provider.run_arm(parameters["provider_config"], replay_record=replay,
+                arm_payload=arm["payload"], seed=17, role=role, work_dir=work)
+            # Preserve raw evidence even if the following budget/runtime audit fails.
+            _create_only(work / "trace.json", dict(result.trace))
+            if result.runtime_instance_id in runtime_ids:
+                raise OfficialArenaError("Retail paired arms reused one native runtime")
+            runtime_ids.add(result.runtime_instance_id)
+            usage = merge_usage(intervention_usage(arm["payload"]), result.usage)
+            shared._validate_shared_budget_usage(arm["payload"], usage)
+            # The host process bridge accepts exactly these five public fields.
+            # Additional diagnostics belong in retained private arm evidence,
+            # not in a response that the bridge will reject as schema drift.
+            row = {"role": role, "arm_id": arm["arm_id"], "metrics": dict(result.metrics),
+                   "trace_hash": content_hash(result.trace),
+                   "usage": {name: usage[name] for name in shared._USAGE_FIELDS}}
+            results.append(row)
+            receipts.append({"role": role, "arm_id": arm["arm_id"], "origin_state_hash": request["origin_state_hash"],
+                "replay_identity": request["replay_identity"], "seed": 17, "locked_dependency_hashes": request["locked_dependency_hashes"],
+                "runtime_instance_id": result.runtime_instance_id, "completed": True})
+            outcome = {"status": "scored_terminal", "result": row,
+                       "trace_measurement": shared._safe_trace_measurement(result.trace),
+                       "intervention_failure": shared._intervention_failure(arm["payload"])}
+        except Exception as error:
+            outcome = {"status": "failed_unscored", "exception_type": type(error).__name__,
+                       "exception_sha256": hashlib.sha256(str(error).encode()).hexdigest(),
+                       "retry_permitted": False, "paper_endpoint": None}
+            failures.append(role)
+        _create_only(work / "arm-outcome.json", _sealed(outcome))
+    response = None
+    if not failures:
+        receipt = {**{name: request[name] for name in ("benchmark_id", "checkpoint_id", "source_revision",
+            "origin_state_hash", "replay_identity", "seed", "locked_dependency_hashes")},
+            **{name: parameters[name] for name in ("bridge_id", "bridge_revision", "scorer_id", "scorer_revision")}, "arms": receipts}
+        response = {"schema_version": 1, "protocol": shared.RESPONSE_PROTOCOL,
+                    "request_hash": value["request_hash"], "receipt": receipt, "arms": results}
+        _create_only(root / "response.json", response)
+    terminal = {"protocol": "retail-pair-terminal.v1", "request_hash": value["request_hash"], "scope_sha256": scope_sha,
+        "status": "failed_unscored" if failures else "paired_scored", "failed_roles": failures,
+        "physical_arm_attempts": 2, "retry_permitted": False, "files": _files(root),
+        "response_sha256": content_hash(response) if response else None}
+    _create_only(root / "terminal.json", _sealed(terminal))
+    if failures:
+        raise RetailAttemptUnavailable("Retail arm failure retained; both arms have dispositions, no retry")
+    return response
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(description="Execute one frozen Retail pair, retaining first attempts")
+    parser.add_argument("--doctor", action="store_true")
+    args = parser.parse_args()
+    if args.doctor:
+        print(json.dumps({"protocol": shared.WORKER_PROTOCOL, "worker_available": True,
+                          "scientific_ready": False, "requires_bound_execution_scope": True}))
+        return 0
+    try:
+        response = run(json.load(sys.stdin, object_pairs_hook=_reject_duplicate_keys))
+    except Exception as error:
+        print(json.dumps({"error": type(error).__name__, "message": "Retail rejected or retained an unscored attempt; inspect owned ledger"}), file=sys.stderr)
+        return 2
+    print(json.dumps(response, sort_keys=True, ensure_ascii=False, allow_nan=False))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

workers/qrag/README.md

@@ -0,0 +1,172 @@
+# Q-RAG frozen-checkpoint sidecar
+
+This directory is an **inference-only compatibility bridge** for
+`griver/Q-RAG@e7598130b63eaab868469877e88bcacc59a44efb`. It does not vendor the
+upstream checkout, checkpoint, tokenizer, base embedder, datasets, or reader.
+It does not expose RL/PQN training.
+
+The bounded common-support profile is executable with the repository-level
+driver below. It uses the same six BM25 candidates for both paired arms, lets
+the released frozen policy select exactly two real candidate documents, and
+passes only those documents to the shared downstream LLM. This is the profile
+used for cross-family comparison; it remains distinct from paper-result parity.
+
+## Release boundary
+
+- Source: user-mounted, read-only, repository license `NOASSERTION`. The
+  upstream README claims CC BY 4.0, but there is no root `LICENSE`; the source
+  acknowledgement is a risk acknowledgement, not legal clearance.
+- Checkpoint: user-mounted
+  `Q-RAG/qrag-ft-e5-on-hotpotqa@e0e48389...`, separately acknowledged as
+  CC BY 4.0. `model_best.pt` and `config.yaml` are hash-pinned.
+- Embedder: user-mounted
+  `intfloat/multilingual-e5-large@3d7cfbda...`; mutable `main` is rejected.
+- Reader: a separately pinned controlled factor. The base profile records the
+  upstream QwQ-32B family, but does not claim that the paper's exact reader
+  snapshot is recoverable.
+
+Accordingly, the public result is `controlled_adapter`, not end-to-end
+`official_native` parity. The registry's `native_only` status means only the
+released checkpoint treatment is eligible; it is not a parity claim.
+
+## Preserved algorithm path
+
+The sidecar runtime must call the official candidate/environment construction,
+`PQN.select_action(..., random=False, evaluate=True)`, and `QAEnv.step`. Every
+step records the available candidate indices, full finite Q-values, selected
+index/Q-value, and accumulated selected document IDs. Q-RAG has no stop action:
+termination is `fixed_step_budget`, `candidate_exhausted`, or
+`empty_candidates`.
+
+To avoid evaluation-label leakage, the runtime must construct `answer=""` and
+`sf_idx=[]` internally and use upstream `DummyFeedbackModel`. It must never
+load `GroundTruthFeedback`, compute EM/F1/reward, import `train_q_rag.py`, or
+call optimizer/scheduler/update/save methods. This changes the paper's
+ground-truth-assisted early termination and is why parity is not claimed.
+
+## Security contract
+
+The published 20 GB `model_best.pt` is a pickle checkpoint and upstream
+`PQN.load` calls `torch.load(weights_only=False)`. Do **not** call that loader.
+The dedicated runtime must use `torch.load(..., weights_only=True)`, validate
+the expected inference keys, and call inference-module `load_state_dict` with
+`strict=True`; optimizer and scheduler state are ignored. Run as non-root with
+no network during selector construction, read-only mounts, no host secrets,
+and CPU/GPU/memory/time limits. For production, a one-time isolated conversion
+to a tensor-only artifact is preferred and must bind both source and converted
+manifests.
+
+The released file also serializes an OmegaConf `ListConfig` inside ignored
+scheduler state. The common-support runtime therefore wraps the weights-only
+load in a scoped allowlist containing only the inert OmegaConf metadata/node
+constructors and built-in containers required by this exact pinned artifact.
+Any other Python global still fails closed; the unsafe upstream loader is never
+called.
+
+`QRAGFrozenDriver` performs all license, source, checkpoint, embedder,
+candidate order, profile, horizon, Q-value, usage, and response-attestation
+checks before returning a successful envelope. `runtime_factory` and `reader`
+are explicit dependency seams; the CI fake uses them without weakening the
+production manifest.
+
+### Reader budget configuration (protocol v3)
+
+`QRAGControls(max_output_tokens=...)` sets the reader's per-call output ceiling;
+4000 is the upstream default, not a hard minimum. `ExecutionBudget` independently
+sets cumulative run limits. The effective reader cap is the smaller of the
+configured ceiling and remaining output tokens. With no remaining tokens or
+model calls, execution stops before constructing the selector runtime.
+
+The reader callable has the signature
+`reader(question, passages, artifacts, *, max_output_tokens) -> ReaderResult`.
+It must send that effective ceiling to its actual model request, use its pinned
+deployment, and avoid hidden retries. A legacy three-argument reader is rejected
+before selector work. Return actual provider input/output usage, including
+reasoning tokens where reported; do not replace missing usage with zero.
+
+Both ends bind and verify the requested/effective budget in the v3 envelope.
+The response records `reader_budget`, including `preset="upstream_default"` or
+`"custom"`; actual usage above the effective ceiling is a consumed failure.
+v2 requests/responses are not silently accepted under this changed contract.
+No checkpoint, selector horizon, prompt or historical result changes with this
+configuration support. End-to-end paper parity is not claimed for either budget.
+
+### Explicit instruction-preserving QA adapter
+
+`reader_profile="factorial_instruction_preserving_reader_transfer"` is an
+opt-in transfer variant, with `QRAG_INSTRUCTION_PROMPT_SHA256` and protocol
+`agentinputlab.qrag.instruction_reader.v1`. The original two question-only
+profiles retain protocol v3 and their original prompts. They are not silently
+converted into this adapter.
+
+Its callback must accept `max_output_tokens`, `task_instruction` and
+`passage_annotations` as keyword arguments. Call the shipped
+`render_instruction_reader_prompt(question, passages, task_instruction=...,
+passage_annotations=...)` and use `QRAG_INSTRUCTION_SYSTEM_PROMPT` in the
+actual model request. Task instruction and visible passage annotations are
+hash-bound, preserved in selection order, and included only in the reader;
+the frozen selector's question/candidate input is unchanged. This variant
+rejects conversation history and tool execution. No labels reach the policy.
+
+The final JSON schema contains `answer` and the three string arrays
+`support_ids`, `evidence_ids`, `evidence_texts`. The parser accepts explicit
+final JSON, not reasoning salvage or automatic evidence inference. Score the
+model's predictions with the original benchmark adapter, retain zero scores
+and malformed outputs, and record actual costs without retries. This is a
+labelled prompt/input adaptation, not upstream native parity.
+
+IR native-query decoding is a separate opt-in postprocessor:
+`parse_native_query_reader_answer(final_text)`, identified by
+`QRAG_NATIVE_QUERY_DECODER_ID`/`QRAG_NATIVE_QUERY_DECODER_SHA256`. It accepts
+exact final `{"query": "nonempty text"}` JSON, not a QA wrapper or inferred
+query. The worker's generated text, prompts, budgets and usage stay unchanged.
+Use the returned query with the original corpus/ranker/native scorer, retain
+the raw output and any original QA-decoding rejection, and record the selected
+decoder alongside the new score. This path does not retry generation.
+
+The pinned upstream `DummyFeedbackModel` omits the abstract `reset` method and
+therefore cannot be instantiated with current Python ABC enforcement. The
+runtime supplies only that missing lifecycle method by delegating to the
+upstream `AFeedbackModel.reset`; it does not alter feedback, reward,
+termination, candidate construction, Q-values, or the two-step PQN policy.
+
+## Installed common-support API
+
+Install the `qrag` extra in the dedicated non-root environment. Source,
+checkpoint and embedder mounts remain operator-provided; acknowledge their
+separate licenses before execution. The public distribution does not include
+research campaign scripts or previous experiment results.
+
+The installed API is
+`agentinputlab.algorithms.acquire.qrag.LocalQRAGFrozenPolicyRuntime`. Construct
+it with `source_root`, `checkpoint_root`, `embedder_root`,
+`compatibility_manifest_path`, `compatibility_manifest_sha256`,
+`embedder_manifest_sha256` and an explicit `device` (`cpu` or the operator's
+authorized CUDA device). Both manifest hashes use
+`agentinputlab.contracts.serialization.content_hash` on their parsed JSON
+objects. The compatibility policy ships as
+`workers/qrag/compatibility_manifest.json`; the embedder manifest belongs to
+the mounted snapshot.
+
+Pass this runtime as `InterventionContext.external_runtime` and a real
+candidate retriever as `InterventionContext.retriever` when running
+`QRAGCommonSupport` through `InterventionRunner`. The runtime loads only the
+frozen selector; the caller runs and scores its separately bound downstream
+model. Construct one runtime per isolated process to avoid sharing upstream
+global PyTorch device or random state with unrelated applications.
+
+`QRAGFrozenDriver` is a separate selector-plus-reader integration class, not a
+ready-made command-line server. `python -m workers.qrag.driver` intentionally
+exits with deployment guidance until an operator supplies its runtime and
+reader. Do not point users at unpublished research-only script paths.
+
+## Checks
+
+```bash
+PYTHONPATH=src:. python -m pytest -q tests/workers/test_qrag_worker_driver.py
+PYTHONPATH=src:. python -m pytest -q tests/algorithms/unit/test_remaining_runtime.py -k qrag
+```
+
+Set `AGENTINPUTLAB_RUN_REAL_QRAG_IMPORT_SMOKE=1` and
+`AGENTINPUTLAB_QRAG_CHECKOUT=/read-only/Q-RAG` to run the opt-in symbol/hash
+smoke. It does not deserialize or download a checkpoint.

workers/qrag/__init__.py

@@ -0,0 +1 @@
+"""User-mounted Q-RAG frozen-checkpoint worker."""