consequa-x 0.1.0a2__py3-none-any.whl

consequa_x/benchmark/calibration_export.py

@@ -0,0 +1,139 @@
+"""Portable, deterministic evidence exports for the offline calibration probe."""
+
+from contextlib import ExitStack
+import gzip
+from hashlib import sha256
+import json
+from pathlib import Path
+
+from .. import __version__
+from ..models import to_dict
+from ..schema import get_trace_schema
+from .calibration import (
+    calibration_protocol, compact_calibration_trial, run_calibration,
+)
+
+
+def _json(value):
+    return json.dumps(to_dict(value), sort_keys=True, allow_nan=False, separators=(",", ":"))
+
+
+def _write_json(path, value):
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(to_dict(value), indent=2, sort_keys=True, allow_nan=False) + "\n",
+                    encoding="utf-8", newline="\n")
+
+
+def export_calibration(plan, output, *, source_revision=None, on_trial=None):
+    """Save the frozen protocol first; retain every compact trial and replicate 0.
+
+    An existing nonempty directory is rejected. Partial exports survive an
+    execution or export error and lack the final completion manifest.
+    """
+    output = Path(output)
+    protocol = calibration_protocol(plan)
+    if on_trial is not None and not callable(on_trial):
+        raise TypeError("on_trial must be callable or None")
+    if source_revision is not None and (not isinstance(source_revision, str)
+                                        or not source_revision.strip()):
+        raise ValueError("source_revision must be a nonempty identifier or None")
+    if output.exists() and (not output.is_dir() or any(output.iterdir())):
+        raise ValueError("calibrate-attribution requires a new or empty output directory")
+    output.mkdir(parents=True, exist_ok=True)
+    _write_json(output / "protocol.json", {"package_version": __version__, **protocol,
+        "source_revision": source_revision,
+        "source_revision_trust": "caller supplied; the exporter does not inspect Git",
+        "retention": {"all_trials": "trials/<mechanism>.jsonl.gz",
+                      "full_evidence_replicates": [0],
+                      "selection": "replicate 0, every attempted branch, including failures",
+                      "gzip_mtime": 0}})
+    _write_json(output / "trace-schema.json", get_trace_schema())
+
+    def gz_write(path, value):
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("wb") as raw:
+            with gzip.GzipFile(filename="", fileobj=raw, mode="wb", mtime=0) as stream:
+                stream.write((_json(value) + "\n").encode("utf-8"))
+
+    def evidence(trial):
+        public = {"seed_plan": to_dict(trial.seed_plan), "methods": {}}
+        gold = {"seed_plan": to_dict(trial.seed_plan), "methods": {}}
+        for method, factual, decisions, experiment in (
+            ("contrastive", trial.factual, trial.factual_decisions, trial.contrastive),
+            ("shapley", trial.shapley_factual, trial.shapley_factual_decisions, trial.shapley),
+        ):
+            episodes = [("factual", factual, decisions)]
+            if experiment is not None:
+                for branch in experiment.branches:
+                    index = branch.index if method == "contrastive" else branch.slot.index
+                    episodes.append((f"branch_{index}", branch.replay.episode,
+                                     branch.replay.decisions))
+            public["methods"][method] = {}
+            gold["methods"][method] = {}
+            for key, episode, receipts in episodes:
+                record = {"decisions": to_dict(receipts)}
+                if episode is not None:
+                    record.update(trace=to_dict(episode.trace),
+                                  explanation=episode.explanation.to_dict())
+                    gold["methods"][method][key] = {
+                        "config": to_dict(episode.config), "seed": episode.seed,
+                        "records": to_dict(episode.ground_truth)}
+                public["methods"][method][key] = record
+        gz_write(output / "evidence" / f"{trial.seed_plan.mechanism}.json.gz", public)
+        gz_write(output / "evaluator_truth" / f"{trial.seed_plan.mechanism}.json.gz", gold)
+
+    with ExitStack() as stack:
+        streams = {}
+        for name in plan.mechanisms:
+            path = output / "trials" / f"{name}.jsonl.gz"
+            path.parent.mkdir(parents=True, exist_ok=True)
+            raw = stack.enter_context(path.open("wb"))
+            streams[name] = stack.enter_context(gzip.GzipFile(
+                filename="", fileobj=raw, mode="wb", mtime=0))
+
+        def retain(trial):
+            record = compact_calibration_trial(trial).to_dict()
+            streams[trial.seed_plan.mechanism].write((_json(record) + "\n").encode("utf-8"))
+            if trial.seed_plan.replicate == 0:
+                evidence(trial)
+            if on_trial is not None:
+                on_trial(trial)
+            if trial.seed_plan.replicate == plan.repeats - 1:
+                print(f"Completed {trial.seed_plan.mechanism}: {plan.repeats} planned trials",
+                      flush=True)
+
+        result = run_calibration(plan, on_trial=retain)
+
+    summary = result.summary()
+    _write_json(output / "summary.json", {"package_version": __version__, **summary})
+    report = (
+        "# Synthetic attribution calibration probe\n\n"
+        f"{len(result.trials)} predeclared trials across {len(plan.mechanisms)} mechanisms; "
+        f"{plan.repeats} repetitions each. No language model was called.\n\n"
+        "`protocol.json` was saved before policy calls. `summary.json` reports "
+        "availability, reference eligibility, error and interval coverage with explicit "
+        "denominators. All planned draws and refusal receipts are in compressed JSONL "
+        "files under `trials/`. Full public traces, explanations and decision receipts "
+        "for replicate 0 are in `evidence/`; its gold records stay separately in "
+        "`evaluator_truth/`. Python's standard `gzip` module can read these files.\n\n"
+        "The policy has a declared fixed factual timeout intervention and stochastic "
+        "fresh continuations. Analytic references describe its ideal Bernoulli law, "
+        "not the observed replay sample. The three-position retry game has undefined "
+        "population Shapley values when some held positions are unreachable. Available "
+        "finite estimates there are not scored against fabricated truth.\n\n"
+        "Missing provenance, stale readback and the three-call budget control are "
+        "intentional refusal strata. Refusals remain in planned denominators. "
+        "State and linked targets reuse outcomes and are not independent replications. "
+        "This exploratory synthetic probe does not establish calibrated coverage, "
+        "model accuracy, interaction recovery or method superiority.\n\n"
+        "The file manifest detects changed bytes, not authenticity. The detailed "
+        "design and metric definitions are in `docs/attribution-calibration.md`.\n"
+    )
+    (output / "README.md").write_text(report, encoding="utf-8", newline="\n")
+    artifacts = [{"path": path.relative_to(output).as_posix(),
+                  "sha256": sha256(path.read_bytes()).hexdigest(), "bytes": path.stat().st_size}
+                 for path in sorted(output.rglob("*")) if path.is_file()]
+    _write_json(output / "manifest.json", {"package_version": __version__,
+                                          "status": "completed", "artifacts": artifacts})
+    print(f"Saved calibration probe in {output.resolve()}")
+    return result

consequa_x/benchmark/calibration_mechanisms.py

@@ -0,0 +1,266 @@
+"""Predeclared synthetic refund mechanisms with analytic population references.
+
+The factual timeout choice is a benchmark intervention at one declared phase
+key, not a naturally sampled factual trajectory. Every other timeout choice
+uses a seeded Bernoulli retry law. Policies read public requests only; the
+reference below never observes a rollout, its labels, or its sampled seeds.
+All effects still come from the ordinary isolated ``PaymentWorld`` runner.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+import math
+import random
+from types import MappingProxyType
+from typing import Literal
+
+from ..models import AssessmentStatus, ResponseStatus
+from ..policies import PolicyDecision, PolicyError, PolicyReply, PolicyRequest, validate_seed
+from .payments import Fault
+from .policy_runner import MAX_TRIAL_SEED, run_policy_scenario
+from .runner import Episode, RefundContext, ScenarioConfig
+
+
+TARGETS = ("action", "consequence", "action_linked_consequence")
+
+
+@dataclass(frozen=True)
+class SeededRetryCalibrationPolicy:
+    """Transparent benchmark policy, including its reserved factual phase key.
+
+    Selection always refunds and the final response always stops. A timeout
+    with attempts remaining retries with probability ``retry_probability``
+    except at the exact reserved key, where the predeclared factual operation
+    is forced. The same policy identity must be used for factual and replay.
+    This conditioning is deliberately not a model or population factual draw.
+    """
+
+    retry_probability: float
+    factual_operation: Literal["stop", "retry"] = "stop"
+    factual_policy_seed: int = 0
+
+    def __post_init__(self) -> None:
+        _probability(self.retry_probability)
+        _operation(self.factual_operation)
+        _trial_seed(self.factual_policy_seed)
+
+    @property
+    def metadata(self) -> dict:
+        return {
+            "provider": "synthetic",
+            "policy": "conditioned-bernoulli-refund-calibration",
+            "version": "1",
+            "retry_probability": self.retry_probability,
+            "selection": "always_refund",
+            "conditioning": {
+                "kind": "predeclared_factual_timeout_intervention",
+                "naturally_sampled_factual": False,
+                "reserved_timeout_model_seed": self.factual_policy_seed * 6 + 1,
+                "operation": self.factual_operation,
+            },
+            "continuation_rng": "python_random.Random(model_phase_seed)",
+            "hidden_evidence_inputs": False,
+        }
+
+    def decide(self, request: PolicyRequest, *, seed: int) -> PolicyReply:
+        if not isinstance(request, PolicyRequest):
+            raise PolicyError("Expected a PolicyRequest")
+        validate_seed(seed)
+        # Only the public stage, remaining attempts and response status are used.
+        # No task fault, independent readback, or evaluator truth is supplied.
+        if request.stage == "select":
+            decision = PolicyDecision("refund", rationale="The fixture always selects the refund.")
+            source = "fixed_selection"
+        elif request.responses[-1].status is ResponseStatus.TIMEOUT and request.attempts_remaining:
+            forced = seed == self.factual_policy_seed * 6 + 1
+            retry = self.factual_operation == "retry" if forced else (
+                random.Random(seed).random() < self.retry_probability
+            )
+            decision = PolicyDecision("retry" if retry else "stop", AssessmentStatus.UNKNOWN,
+                                      "The fixture applies its declared timeout retry rule.")
+            source = "reserved_factual_intervention" if forced else "seeded_bernoulli_retry"
+        else:
+            decision = PolicyDecision("stop", AssessmentStatus.UNKNOWN,
+                                      "The fixture stops after the final or non-timeout response.")
+            source = "fixed_final_stop"
+        return PolicyReply(decision, {"seed": seed, "decision_source": source})
+
+
+def _probability(value: float) -> None:
+    if type(value) not in (int, float) or not math.isfinite(value) or not 0 <= value <= 1:
+        raise ValueError("retry_probability must be a finite probability in 0..1")
+
+
+def _operation(value: str) -> None:
+    if type(value) is not str or value not in {"stop", "retry"}:
+        raise ValueError("factual_operation must be stop or retry")
+
+
+def _trial_seed(value: int) -> None:
+    if type(value) is not int or not 0 <= value <= MAX_TRIAL_SEED:
+        raise ValueError(f"factual_policy_seed must be an integer in 0..{MAX_TRIAL_SEED}")
+
+
+@dataclass(frozen=True)
+class CalibrationMechanism:
+    """One world configuration and its independently specified retry law."""
+
+    name: str
+    retry_probability: float
+    factual_operation: Literal["stop", "retry"] = "stop"
+    use_idempotency: bool = False
+    include_provenance: bool = True
+    read_lag_ms: int = 0
+
+    def __post_init__(self) -> None:
+        if type(self.name) is not str or not self.name.strip():
+            raise ValueError("name must be a nonempty string")
+        _probability(self.retry_probability)
+        _operation(self.factual_operation)
+        if type(self.use_idempotency) is not bool or type(self.include_provenance) is not bool:
+            raise ValueError("use_idempotency and include_provenance must be booleans")
+        if type(self.read_lag_ms) is not int or self.read_lag_ms < 0:
+            raise ValueError("read_lag_ms must be a nonnegative integer")
+
+    @property
+    def decision_count(self) -> int:
+        return 2 if self.factual_operation == "stop" else 3
+
+    def make_policy(self, *, factual_policy_seed: int = 0) -> SeededRetryCalibrationPolicy:
+        return SeededRetryCalibrationPolicy(
+            self.retry_probability, self.factual_operation, factual_policy_seed,
+        )
+
+    def scenario_config(self) -> ScenarioConfig:
+        return ScenarioConfig(
+            name=self.name, fault=Fault.TIMEOUT_AFTER_COMMIT,
+            context=RefundContext(retry_instruction=True),
+            use_idempotency=self.use_idempotency,
+            include_provenance=self.include_provenance, read_lag_ms=self.read_lag_ms,
+        )
+
+    def capture_factual(self, *, seed: int = 0, policy_seed: int = 0) -> Episode:
+        """Convenience capture; budgeted callers should use the ordinary runner."""
+        return run_policy_scenario(
+            self.scenario_config(), self.make_policy(factual_policy_seed=policy_seed),
+            seed=seed, policy_seed=policy_seed, max_attempts=2,
+        )
+
+    def analytic_reference(self) -> dict:
+        """Describe the ideal Bernoulli game without running or reading episodes.
+
+        Coalition arrays use integer bit masks: bit ``i`` holds decision ``i``.
+        An undefined coalition retains ``None`` rather than a conditional mean
+        among valid rollouts. Retry factuals can stop before their held final
+        decision, so they have no complete Shapley population game for q < 1.
+        Endpoint truth remains available when both complete endpoints are known.
+        """
+        n, q = self.decision_count, self.retry_probability
+        retry_factual = self.factual_operation == "retry"
+        valid = [q if n == 3 and mask & 4 and not mask & 2 else 1.
+                 for mask in range(1 << n)]
+        targets = {}
+        for target in TARGETS:
+            evidence_unknown = target != "action" and (
+                bool(self.read_lag_ms)
+                or (target == "action_linked_consequence" and not self.include_provenance)
+            )
+            # Without provenance, a duplicate still violates the state contract
+            # and has a known false linked target. The protective factual and
+            # held-stop coalitions nevertheless remain unknown.
+            factual_known_violation = retry_factual and not self.use_idempotency
+            factual_bad = (False if target == "action" else (
+                None if self.read_lag_ms else (
+                    True if factual_known_violation else (None if evidence_unknown else False)
+                )
+            ))
+            numeric = not evidence_unknown
+            if target == "action":
+                changed = [0.] * n
+                coalition = [0. if probability == 1 else None for probability in valid]
+            elif numeric:
+                fresh_bad = 0. if self.use_idempotency else float(q)
+                changed = [fresh_bad, fresh_bad] + ([float(bool(factual_bad))] if n == 3 else [])
+                coalition = [
+                    None if valid[mask] < 1 else (
+                        float(bool(factual_bad)) if mask & 2 else fresh_bad
+                    )
+                    for mask in range(1 << n)
+                ]
+            else:
+                # With missing provenance, a fresh draw that necessarily
+                # duplicates is still a known violation. All other fresh laws
+                # have positive unknown probability and no binary mean.
+                fresh_bad = (1. if not self.read_lag_ms and not self.use_idempotency and q == 1
+                             else None)
+                changed = [fresh_bad, fresh_bad] + (
+                    [float(factual_bad) if factual_bad is not None else None] if n == 3 else []
+                )
+                coalition = [
+                    None if valid[mask] < 1 else (
+                        float(factual_bad) if factual_bad is not None else None
+                    ) if mask & 2 else fresh_bad for mask in range(1 << n)
+                ]
+            effects = [None if rate is None or factual_bad is None else rate - int(factual_bad)
+                       for rate in changed]
+            contrastive_eligible = factual_bad is not None and all(value is not None for value in effects)
+            shapley_eligible = all(value is not None for value in coalition)
+            endpoint_eligible = coalition[0] is not None and coalition[-1] is not None
+            if shapley_eligible:
+                # The initial selection is always the same operation; holding
+                # the timeout choice alone changes the population retry rate.
+                shares = [0., coalition[2] - coalition[0]] + ([0.] if n == 3 else [])
+            else:
+                shares = None
+            latest = max((i for i, effect in enumerate(effects) if effect is not None and effect < 0),
+                         default=None) if contrastive_eligible else None
+            unknown_reason = "independent outcome evidence is unknown"
+            invalid_reason = "a fresh timeout stop can make held terminal decision 2 unreachable"
+            targets[target] = {
+                "factual_bad": factual_bad,
+                "changed_bad_rates": changed,
+                "contrastive_effects": effects,
+                "latest_population_rescue": latest,
+                "coalition_bad_rates": coalition,
+                "contrastive_eligible": contrastive_eligible,
+                "shapley_eligible": shapley_eligible,
+                "endpoint_eligible": endpoint_eligible,
+                "shapley_values": shares,
+                "endpoint_difference": coalition[-1] - coalition[0] if endpoint_eligible else None,
+                "contrastive_null_positions": [i for i, effect in enumerate(effects) if effect == 0],
+                "shapley_null_positions": [i for i, share in enumerate(shares or ()) if share == 0],
+                "reasons": {
+                    "contrastive": None if contrastive_eligible else unknown_reason,
+                    "shapley": None if shapley_eligible else (
+                        invalid_reason if any(probability < 1 for probability in valid) else unknown_reason
+                    ),
+                    "endpoint": None if endpoint_eligible else unknown_reason,
+                },
+            }
+        return {
+            "name": self.name, "decision_count": n,
+            "retry_probability": q,
+            "conditioning": "fixed factual timeout intervention; ideal Bernoulli continuation law",
+            "population_not_finite_seed_claim": True,
+            "coalition_valid_probabilities": valid,
+            "targets": targets,
+        }
+
+
+CALIBRATION_MECHANISMS = MappingProxyType({
+    **{f"protective-stop-q{int(q * 100)}": CalibrationMechanism(f"protective-stop-q{int(q * 100)}", q)
+       for q in (.1, .5, .9)},
+    **{f"retry-pivot-q{int(q * 100)}": CalibrationMechanism(f"retry-pivot-q{int(q * 100)}", q, "retry")
+       for q in (.1, .5, .9)},
+    "idempotent-stop-q50": CalibrationMechanism("idempotent-stop-q50", .5, use_idempotency=True),
+    "unknown-provenance-stop-q50": CalibrationMechanism("unknown-provenance-stop-q50", .5,
+                                                       include_provenance=False),
+    "lagged-readback-stop-q50": CalibrationMechanism("lagged-readback-stop-q50", .5, read_lag_ms=1000),
+})
+
+
+def get_calibration_mechanism(name: str) -> CalibrationMechanism:
+    if type(name) is not str or name not in CALIBRATION_MECHANISMS:
+        raise ValueError(f"Unknown calibration mechanism: {name!r}")
+    return CALIBRATION_MECHANISMS[name]

consequa_x/benchmark/decision_coalition.py

@@ -0,0 +1,254 @@
+"""Replay positional coalitions of captured decisions in isolated worlds.
+
+A held position forces its captured decision at the same typed policy stage.
+Earlier fresh decisions may change its public request, so this intervention does
+not require the exact request equality used by decision-prefix replay. An absent
+held position invalidates a branch by default. The separate on-reach game
+records normally terminated later held positions as inactive.
+"""
+
+from __future__ import annotations
+
+from copy import deepcopy
+from dataclasses import dataclass
+from typing import Iterable, Literal
+
+from ..models import to_dict
+from ..policies import PolicyError, PolicyReply, PolicyRequest, validate_reply
+from .decision_replay import (
+    DecisionReplayReceipt, _Capture, _json_key, _metadata, _validate_factual,
+)
+from .evaluation import BudgetedPolicy, CallBudgetExceeded
+from .policy_runner import MAX_TRIAL_SEED, run_policy_scenario
+from .runner import Episode
+from .templates import DEFAULT_REFUND_TEMPLATE, RefundTaskTemplate
+
+
+COALITION_GAMES = ("strict", "on_reach")
+
+
+def validate_coalition_game(game):
+    if type(game) is not str or game not in COALITION_GAMES:
+        raise ValueError("coalition_game must be strict or on_reach")
+
+
+class DecisionCoalitionIncompatible(PolicyError):
+    """A forced factual decision is incompatible with its reached boundary."""
+
+
+class DecisionCoalitionUnreachable(PolicyError):
+    """A completed rollout stopped before a required held position."""
+
+
+@dataclass(frozen=True)
+class DecisionCoalitionReplay:
+    """One coalition branch, including partial receipts after failure."""
+
+    held_indices: tuple[int, ...]
+    continuation_seed: int
+    factual_seed: int
+    factual_decision_count: int
+    policy_metadata: dict
+    decisions: tuple[DecisionReplayReceipt, ...]
+    policy_calls: int
+    episode: Episode | None = None
+    error_type: str | None = None
+    error: str | None = None
+    budget_exhausted: bool = False
+    coalition_game: str = "strict"
+
+    @property
+    def status(self) -> Literal["completed", "invalid", "failed"]:
+        if self.episode is not None:
+            return "completed"
+        if self.error_type in {
+            "DecisionCoalitionIncompatible", "DecisionCoalitionUnreachable",
+        }:
+            return "invalid"
+        return "failed"
+
+    @property
+    def unreached_factual_indices(self) -> tuple[int, ...]:
+        return tuple(range(min(len(self.decisions), self.factual_decision_count),
+                           self.factual_decision_count))
+
+    @property
+    def unreached_held_indices(self) -> tuple[int, ...]:
+        return tuple(index for index in self.held_indices if index >= len(self.decisions))
+
+    @property
+    def inactive_held_indices(self) -> tuple[int, ...]:
+        """Only normal termination in the declared on-reach game is inactivity."""
+        return (self.unreached_held_indices
+                if self.coalition_game == "on_reach" and self.episode is not None else ())
+
+    def summary(self) -> dict:
+        return {
+            "status": self.status,
+            "coalition_game": self.coalition_game,
+            "inactive_held_indices": list(self.inactive_held_indices),
+            "held_indices": list(self.held_indices),
+            "continuation_seed": self.continuation_seed,
+            "factual_seed": self.factual_seed,
+            "factual_decision_count": self.factual_decision_count,
+            "reached_decisions": len(self.decisions),
+            "held_decisions": sum(item.source == "held_factual" and item.reply is not None
+                                  for item in self.decisions),
+            "resampled_decisions": sum(item.source == "resampled" and item.reply is not None
+                                       for item in self.decisions),
+            "held_requests": sum(item.source == "held_factual" for item in self.decisions),
+            "resampled_requests": sum(item.source == "resampled" for item in self.decisions),
+            "failed_decisions": sum(item.error_type is not None for item in self.decisions),
+            "unreached_factual_indices": list(self.unreached_factual_indices),
+            "unreached_held_indices": list(self.unreached_held_indices),
+            "policy_calls": self.policy_calls,
+            "budget_exhausted": self.budget_exhausted,
+            "error_type": self.error_type,
+            "error": self.error,
+        }
+
+
+class _CoalitionPolicy:
+    def __init__(self, captures: tuple[_Capture, ...], policy: BudgetedPolicy,
+                 held_indices: tuple[int, ...]):
+        self.captures = captures
+        self.policy = policy
+        self.held_indices = frozenset(held_indices)
+        self.receipts: list[DecisionReplayReceipt] = []
+        self._metadata = deepcopy(captures[0].policy_metadata)
+
+    @property
+    def metadata(self):
+        return deepcopy(self._metadata)
+
+    def decide(self, request: PolicyRequest, *, seed: int) -> PolicyReply:
+        index = len(self.receipts)
+        capture = self.captures[index] if index < len(self.captures) else None
+        source = "held_factual" if index in self.held_indices else "resampled"
+        before = self.policy.calls
+        request_data = to_dict(request)
+        reply = None
+        error = None
+        try:
+            if source == "held_factual":
+                if request.stage != capture.request.stage:
+                    raise DecisionCoalitionIncompatible(
+                        "Held decision reached a different typed policy stage",
+                    )
+                reply = PolicyReply(deepcopy(capture.reply.decision), {
+                    "decision_coalition_replay": {
+                        "source": "forced_factual", "provider_call": False,
+                        "factual_index": index,
+                        "factual_event_id": capture.event_id,
+                        "factual_model_seed": capture.model_seed,
+                        "requested_continuation_model_seed": seed,
+                        "exact_request_match": _json_key(request) == _json_key(capture.request),
+                        "factual_reply_metadata": deepcopy(capture.reply.metadata),
+                    },
+                })
+                try:
+                    validate_reply(request, reply)
+                except (PolicyError, TypeError, ValueError) as caught:
+                    raise DecisionCoalitionIncompatible(
+                        f"Held decision is invalid for the current public request: {caught}",
+                    ) from caught
+            else:
+                if _json_key(_metadata(self.policy)) != _json_key(self._metadata):
+                    raise PolicyError("Continuation policy metadata differs from factual policy")
+                reply = self.policy.decide(deepcopy(request), seed=seed)
+                if _json_key(_metadata(self.policy)) != _json_key(self._metadata):
+                    raise PolicyError("Continuation policy metadata changed during its decision")
+                validate_reply(request, reply)
+            reply = deepcopy(reply)
+            return reply
+        except (PolicyError, TypeError, ValueError) as caught:
+            error = caught
+            raise
+        finally:
+            self.receipts.append(DecisionReplayReceipt(
+                index, source, request.stage, seed,
+                capture.event_id if capture else None, capture.model_seed if capture else None,
+                self.policy.calls - before, request_data,
+                to_dict(reply) if reply is not None and error is None else None,
+                type(error).__name__ if error else None, str(error) if error else None,
+            ))
+
+
+def replay_decision_coalition(
+    factual: Episode,
+    continuation_policy: BudgetedPolicy,
+    *,
+    held_indices: Iterable[int],
+    continuation_seed: int,
+    template: RefundTaskTemplate = DEFAULT_REFUND_TEMPLATE,
+    coalition_game: str = "strict",
+) -> DecisionCoalitionReplay:
+    """Reset the factual world and force the requested positional decisions.
+
+    Full factual captures and declared policy identity are validated without
+    provider calls before running a branch. Held decisions consume zero calls;
+    fresh decisions use a shared actual-call budget. New reached positions beyond
+    the factual trace are fresh. A branch may stop before unheld positions, but
+    stopping before a held position invalidates a strict-game branch. In the
+    explicit on-reach game, normally unreached held positions are inactive;
+    the completed episode and its verified outcome remain the actual rollout.
+    A reached but incompatible held decision is invalid under either game.
+
+    Forced decisions are positional interventions, including their captured
+    assessment and reported rationale. They need not be decisions the policy
+    would choose under a changed request. Same-stage and current-reply validity
+    checks keep this distinction explicit. Seeds do not establish model
+    independence or hidden-state identity.
+    """
+    if not isinstance(factual, Episode):
+        raise TypeError("factual must be an Episode")
+    validate_coalition_game(coalition_game)
+    if not isinstance(continuation_policy, BudgetedPolicy):
+        raise TypeError("continuation_policy must be a BudgetedPolicy")
+    if (type(continuation_policy.max_calls) is not int or continuation_policy.max_calls < 1
+            or type(continuation_policy.calls) is not int
+            or not 0 <= continuation_policy.calls <= continuation_policy.max_calls):
+        raise ValueError("BudgetedPolicy counters must be integers within its valid call limit")
+    if type(continuation_seed) is not int or not 0 <= continuation_seed <= MAX_TRIAL_SEED:
+        raise ValueError(f"continuation_seed must be an integer in 0..{MAX_TRIAL_SEED}")
+    if type(factual.seed) is not int or not 0 <= factual.seed <= MAX_TRIAL_SEED:
+        raise ValueError(f"factual seed must be an integer in 0..{MAX_TRIAL_SEED}")
+    if not isinstance(template, RefundTaskTemplate):
+        raise TypeError("template must be a RefundTaskTemplate")
+    try:
+        positions = tuple(held_indices)
+    except TypeError as caught:
+        raise TypeError("held_indices must be an iterable of decision indices") from caught
+    if any(type(index) is not int or index < 0 for index in positions):
+        raise ValueError("held_indices must contain nonnegative integers")
+    if len(set(positions)) != len(positions):
+        raise ValueError("held_indices must not contain duplicate positions")
+    held = tuple(sorted(positions))
+    captures = _validate_factual(factual, template)
+    if any(index >= len(captures) for index in held):
+        raise ValueError("held_indices exceed the factual captured decision range")
+    metadata = _metadata(continuation_policy)
+    if _json_key(metadata) != _json_key(captures[0].policy_metadata):
+        raise ValueError("Continuation policy metadata differs from factual policy")
+    coalition_policy = _CoalitionPolicy(captures, continuation_policy, held)
+    before = continuation_policy.calls
+    episode = None
+    error = None
+    try:
+        episode = run_policy_scenario(
+            factual.config, coalition_policy, seed=factual.seed, policy_seed=continuation_seed,
+            max_attempts=captures[0].request.attempts_remaining, template=template,
+        )
+        unreached = tuple(index for index in held if index >= len(coalition_policy.receipts))
+        if unreached and coalition_game == "strict":
+            raise DecisionCoalitionUnreachable(f"Held decision positions were not reached: {unreached}")
+    except (PolicyError, TypeError, ValueError) as caught:
+        error = caught
+        episode = None
+    return DecisionCoalitionReplay(
+        held, continuation_seed, factual.seed, len(captures), deepcopy(metadata),
+        tuple(coalition_policy.receipts), continuation_policy.calls - before, episode,
+        type(error).__name__ if error else None, str(error) if error else None,
+        isinstance(error, CallBudgetExceeded),
+        coalition_game,
+    )