consequa-x 0.1.0a2__py3-none-any.whl

consequa_x/benchmark/evaluation.py

@@ -0,0 +1,187 @@
+"""Bounded policy evaluation with failures separate from verified outcomes."""
+
+from dataclasses import dataclass
+from collections.abc import Mapping
+from pathlib import Path
+from typing import Iterable
+
+from ..models import to_dict
+from ..policies import Policy, PolicyError
+from .assessment_metrics import assessment_metrics
+from .policy_runner import MAX_TRIAL_SEED, run_policy_scenario
+from .runner import Episode, ScenarioConfig, demo_scenarios
+from .templates import DEFAULT_REFUND_TEMPLATE, RefundTaskTemplate
+from .targets import action_linked_consequence
+
+
+class CallBudgetExceeded(PolicyError):
+    """The evaluation refused another policy call before invoking the provider."""
+
+
+class BudgetedPolicy:
+    """Count attempted decisions, including provider and protocol failures."""
+
+    def __init__(self, policy: Policy, max_calls: int):
+        if type(max_calls) is not int or max_calls < 1:
+            raise ValueError("max_calls must be a positive integer")
+        self.policy = policy
+        self.max_calls = max_calls
+        self.calls = 0
+
+    @property
+    def metadata(self):
+        return to_dict(self.policy.metadata)
+
+    def decide(self, request, *, seed):
+        if self.calls >= self.max_calls:
+            raise CallBudgetExceeded("The policy-call budget is exhausted")
+        self.calls += 1
+        return self.policy.decide(request, seed=seed)
+
+
+@dataclass(frozen=True)
+class EvaluationSample:
+    index: int
+    scenario: str
+    seed: int
+    policy_calls: int
+    episode: Episode | None = None
+    error_type: str | None = None
+    error: str | None = None
+
+
+@dataclass(frozen=True)
+class PolicyEvaluation:
+    samples: tuple[EvaluationSample, ...]
+    policy_metadata: dict
+    planned_samples: int
+    max_calls: int
+    calls: int
+    budget_exhausted: bool
+
+    def summary(self) -> dict:
+        counts = {name: 0 for name in ("satisfied", "violated", "unknown")}
+        origin = {name: 0 for name in ("confirmed", "other_actor", "unknown")}
+        alignment = {name: 0 for name in ("consistent", "contradicted", "unassessable")}
+        linked = {name: 0 for name in ("satisfied", "not_satisfied", "unknown")}
+        completed = 0
+        for sample in self.samples:
+            if sample.episode is None:
+                continue
+            completed += 1
+            verification = sample.episode.trace.verifications[-1]
+            counts[verification.status.value] += 1
+            origin[verification.origin.value] += 1
+            label = sample.episode.explanation.assessment_alignment
+            alignment[label] = alignment.get(label, 0) + 1
+            value = action_linked_consequence(sample.episode.trace.action, verification)
+            linked["unknown" if value is None else "satisfied" if value else "not_satisfied"] += 1
+        return {
+            "planned_samples": self.planned_samples,
+            "attempted_samples": len(self.samples),
+            "completed_samples": completed,
+            "failed_samples": len(self.samples) - completed,
+            "not_started_samples": self.planned_samples - len(self.samples),
+            "policy_calls": self.calls,
+            "max_calls": self.max_calls,
+            "budget_exhausted": self.budget_exhausted,
+            "verification": counts,
+            "origin": origin,
+            "assessment_alignment": alignment,
+            "action_linked_consequence": linked,
+            "assessment_metrics": assessment_metrics(
+                (sample.episode.trace.assessment.status,
+                 sample.episode.explanation.assessment_alignment)
+                for sample in self.samples if sample.episode is not None
+            ),
+            "known_outcome_samples": counts["satisfied"] + counts["violated"],
+        }
+
+
+def evaluate_policy(policy: Policy, configs: Iterable[ScenarioConfig] | None = None, *,
+                    samples: int = 2, seed: int = 0, max_calls: int = 100,
+                    max_attempts: int = 2,
+                    templates: Mapping[str, RefundTaskTemplate] | None = None) -> PolicyEvaluation:
+    """Evaluate fresh worlds; provider/protocol failures never become violations.
+
+    Model calls are serial and bounded. A failed episode is retained as a failure
+    receipt, not dropped or replaced by a second draw. No model-level attribution
+    or generalization claim follows from these template-level smoke evaluations.
+    """
+    if type(samples) is not int or samples < 1:
+        raise ValueError("samples must be a positive integer")
+    if type(seed) is not int or seed < 0:
+        raise ValueError("seed must be a nonnegative integer")
+    if type(max_attempts) is not int or not 1 <= max_attempts <= 5:
+        raise ValueError("max_attempts must be in 1..5")
+    configurations = tuple(demo_scenarios() if configs is None else configs)
+    if not configurations or any(not isinstance(config, ScenarioConfig) for config in configurations):
+        raise ValueError("configs must contain at least one ScenarioConfig")
+    if len({config.name for config in configurations}) != len(configurations):
+        raise ValueError("scenario names must be unique")
+    if templates is None:
+        template_map = {config.name: DEFAULT_REFUND_TEMPLATE for config in configurations}
+    else:
+        if not isinstance(templates, Mapping) or set(templates) != {
+            config.name for config in configurations
+        } or any(not isinstance(item, RefundTaskTemplate) for item in templates.values()):
+            raise ValueError("templates must map every scenario name to a RefundTaskTemplate")
+        template_map = dict(templates)
+    if seed + len(configurations) * samples - 1 > MAX_TRIAL_SEED:
+        raise ValueError("Evaluation seed schedule exceeds the model seed range")
+    bounded = BudgetedPolicy(policy, max_calls)
+    records = []
+    exhausted = False
+    for config in configurations:
+        for _ in range(samples):
+            if bounded.calls >= max_calls:
+                exhausted = True
+                break
+            index = len(records)
+            calls_before = bounded.calls
+            try:
+                episode = run_policy_scenario(config, bounded, seed=seed + index,
+                                              max_attempts=max_attempts,
+                                              template=template_map[config.name])
+                record = EvaluationSample(index, config.name, seed + index,
+                                          bounded.calls - calls_before, episode)
+            except PolicyError as error:
+                exhausted = isinstance(error, CallBudgetExceeded)
+                record = EvaluationSample(index, config.name, seed + index,
+                                          bounded.calls - calls_before,
+                                          error_type=type(error).__name__, error=str(error))
+            records.append(record)
+            if exhausted:
+                break
+        if exhausted:
+            break
+    return PolicyEvaluation(tuple(records), bounded.metadata, len(configurations) * samples,
+                            max_calls, bounded.calls, exhausted)
+
+
+def evaluation_sample_record(sample: EvaluationSample, *, root: Path | None = None) -> dict:
+    """Return an evaluator receipt without duplicating hidden truth into a trace."""
+    record = {
+        "index": sample.index, "scenario": sample.scenario, "seed": sample.seed,
+        "policy_calls": sample.policy_calls,
+        "status": "completed" if sample.episode is not None else "failed",
+    }
+    if sample.episode is None:
+        record.update(error_type=sample.error_type, error=sample.error)
+    else:
+        episode = sample.episode
+        result = episode.trace.verifications[-1]
+        record.update(
+            action_selected=episode.action_selected,
+            verified_outcome=result.status.value,
+            effect_origin=result.origin.value,
+            reported_assessment=episode.trace.assessment.status.value,
+            assessment_alignment=episode.explanation.assessment_alignment,
+            diagnosis=episode.explanation.diagnosis,
+            action_linked_consequence_satisfied=action_linked_consequence(episode.trace.action, result),
+        )
+        if root is not None:
+            stem = f"episode_{sample.index:04d}.json"
+            record.update(trace=f"traces/{stem}", explanation=f"explanations/{stem}",
+                          evaluator_truth=f"evaluator_truth/{stem}")
+    return record

consequa_x/benchmark/interaction_export.py

@@ -0,0 +1,220 @@
+"""Frozen finite-mixture refund interaction evidence; no live model calls.
+
+Run with ``python -m consequa_x.benchmark.interaction_export --output DIR
+--source-revision COMMIT`` after freezing and checking the source revision.
+"""
+
+from contextlib import ExitStack
+import gzip
+from hashlib import sha256
+import json
+from math import factorial, fsum
+from pathlib import Path
+
+from .. import __version__
+from ..models import to_dict
+from ..schema import get_trace_schema
+from .decision_coalition import replay_decision_coalition
+from .evaluation import BudgetedPolicy
+from .interaction_mechanisms import COMPONENTS, INTERACTION_MECHANISMS, TARGETS
+from .policy_runner import MAX_TRIAL_SEED, run_policy_scenario
+from .targets import episode_outcome
+
+
+def _write(path, value):
+    path.write_text(json.dumps(to_dict(value), indent=2, sort_keys=True, allow_nan=False) + "\n",
+                    encoding="utf-8", newline="\n")
+
+
+def _line(stream, value):
+    stream.write((json.dumps(to_dict(value), sort_keys=True, allow_nan=False,
+                            separators=(",", ":")) + "\n").encode("utf-8"))
+
+
+def _shares(values):
+    if any(value is None for value in values):
+        return None
+    return [fsum(factorial(mask.bit_count()) * factorial(2 - mask.bit_count()) / factorial(3)
+                 * (values[mask | (1 << player)] - values[mask])
+                 for mask in range(8) if not mask & (1 << player)) for player in range(3)]
+
+
+def _summarize_case(mechanism, records):
+    result = {"actual_policy_calls": sum(record["policy_calls"] for record in records), "games": {}}
+    for game in ("strict", "on_reach"):
+        branches = [record for record in records if record["coalition_game"] == game
+                    and record["record_type"] == "branch"]
+        target_summary = {}
+        for target in TARGETS:
+            values, statuses = [], []
+            for mask in range(8):
+                selected = [record for record in branches if record["mask"] == mask]
+                positive = [record for record in selected if record["component_weight"] > 0]
+                invalid = fsum(record["component_weight"] for record in positive
+                               if record["status"] == "invalid")
+                failed = fsum(record["component_weight"] for record in positive
+                              if record["status"] == "failed")
+                unstarted = fsum(record["component_weight"] for record in positive
+                                 if record["status"] == "unstarted")
+                unknown = fsum(record["component_weight"] for record in positive
+                               if record["status"] == "completed"
+                               and record["bad_targets"][target] is None)
+                known = fsum(record["component_weight"] for record in positive
+                             if record["status"] == "completed"
+                             and record["bad_targets"][target] is not None)
+                values.append(None if invalid or failed or unstarted or unknown else
+                    fsum(record["component_weight"] * record["bad_targets"][target]
+                         for record in positive))
+                statuses.append({"known_mass": known, "unknown_mass": unknown,
+                    "invalid_mass": invalid, "failed_mass": failed, "unstarted_mass": unstarted})
+            shares = _shares(values)
+            endpoint = values[7] - values[0] if values[7] is not None and values[0] is not None else None
+            target_summary[target] = {"coalition_bad_rates": values, "mass_by_mask": statuses,
+                "shapley_values": shares, "endpoint_difference": endpoint,
+                "selection_retry_interaction": (values[3] - values[1] - values[2] + values[0]
+                    if all(values[mask] is not None for mask in (0, 1, 2, 3)) else None),
+                "numeric_available": shares is not None}
+        result["games"][game] = {"targets": target_summary,
+            "branch_status_counts": {status: sum(record["status"] == status for record in branches)
+                for status in ("completed", "invalid", "failed", "unstarted")},
+            "inactive_held_branch_count": sum(bool(record["inactive_held_indices"]) for record in branches),
+            "reference": mechanism.analytic_reference(coalition_game=game)}
+    return result
+
+
+def export_refund_interactions(output, *, source_revision, seed=4_000_000, mechanisms=None):
+    """Enumerate actual worlds for every component/game/mask, retaining refusals.
+
+    Each component/game receives a separate budget, including three planted
+    factual calls. Every requested mask is retained. Budgets are never redrawn
+    or enlarged, and zero-mass mixture components remain in the evidence.
+    ``source_revision`` is caller-supplied provenance, not inspected Git state.
+    """
+    if type(source_revision) is not str or not source_revision.strip():
+        raise ValueError("source_revision must be a nonempty frozen source identifier")
+    names = tuple(INTERACTION_MECHANISMS if mechanisms is None else mechanisms)
+    if (not names or any(type(name) is not str or name not in INTERACTION_MECHANISMS for name in names)
+            or len(set(names)) != len(names)):
+        raise ValueError("mechanisms must be unique known names")
+    if type(seed) is not int or not 4_000_000 <= seed <= MAX_TRIAL_SEED - len(names) * 1000:
+        raise ValueError("seed must reserve a disjoint valid phase window starting at 4000000 or later")
+    root = Path(output)
+    if root.exists() and (not root.is_dir() or any(root.iterdir())):
+        raise ValueError("refund interactions require a new or empty output directory")
+    root.mkdir(parents=True, exist_ok=True)
+    schedule = []
+    for case_index, name in enumerate(names):
+        for game_index, game in enumerate(("strict", "on_reach")):
+            for component_index, component in enumerate(COMPONENTS):
+                first = seed + case_index * 1000 + game_index * 400 + component_index * 100
+                schedule.append({"case": name, "coalition_game": game, "component_index": component_index,
+                    "fresh_selection": component[0], "fresh_retry": component[1],
+                    "component_weight": INTERACTION_MECHANISMS[name].component_weights()[component_index],
+                    "factual_world_seed": first, "factual_policy_seed": first,
+                    "branch_continuation_seeds_by_mask": [first + 1 + mask for mask in range(8)],
+                    "max_calls": INTERACTION_MECHANISMS[name].max_calls})
+    _write(root / "protocol.json", {"package_version": __version__, "source_revision": source_revision,
+        "source_revision_trust": "caller supplied; exporter does not inspect Git",
+        "design": "full four-component deterministic mixture, each of eight held masks, both games",
+        "sampling_claim": "finite enumeration of a declared Bernoulli population law; not stochastic observations",
+        "seed": seed, "model_phase_rule": "world/model schedule seed * 6 + reached position",
+        "mask_order": list(range(8)), "targets": TARGETS, "schedule": schedule,
+        "cases": {name: to_dict(INTERACTION_MECHANISMS[name]) for name in names},
+        "retention": "every planned branch including failed, invalid, unstarted and zero-weight components",
+        "budget_rule": "per component/game budget includes three factual calls; stop starting slots at exhaustion",
+        "references": {name: {game: INTERACTION_MECHANISMS[name].analytic_reference(coalition_game=game)
+                              for game in ("strict", "on_reach")} for name in names},
+        "limitations": ["synthetic public-only policy, no live model or independence claim",
+            "exact mixture law does not validate finite permutation sampling",
+            "held decision effects are positional policy interventions, not context/fault attribution",
+            "zero-weight components are evidence only and do not change the population expectation"]})
+    _write(root / "trace-schema.json", get_trace_schema())
+    retained = {name: [] for name in names}
+    with ExitStack() as stack:
+        raw = stack.enter_context((root / "evidence.jsonl.gz").open("wb"))
+        evidence = stack.enter_context(gzip.GzipFile(filename="", fileobj=raw, mode="wb", mtime=0))
+        raw_gold = stack.enter_context((root / "evaluator-truth.jsonl.gz").open("wb"))
+        gold = stack.enter_context(gzip.GzipFile(filename="", fileobj=raw_gold, mode="wb", mtime=0))
+        for entry in schedule:
+            name, game = entry["case"], entry["coalition_game"]
+            mechanism = INTERACTION_MECHANISMS[name]
+            component = (entry["fresh_selection"], entry["fresh_retry"])
+            policy = mechanism.make_policy(factual_policy_seed=entry["factual_policy_seed"], component=component)
+            budget = BudgetedPolicy(policy, entry["max_calls"])
+            factual = run_policy_scenario(mechanism.scenario_config(), budget,
+                seed=entry["factual_world_seed"], policy_seed=entry["factual_policy_seed"], max_attempts=2)
+            base = {"case": name, "coalition_game": game, "component_index": entry["component_index"],
+                    "component_weight": entry["component_weight"], "policy_metadata": policy.metadata}
+            factual_record = {**base, "record_type": "factual", "policy_calls": budget.calls,
+                "trace": factual.trace.to_dict(), "explanation": factual.explanation.to_dict()}
+            _line(evidence, factual_record)
+            retained[name].append(factual_record)
+            _line(gold, {**base, "record_type": "factual", "seed": factual.seed,
+                        "config": to_dict(factual.config), "records": to_dict(factual.ground_truth)})
+            for mask, continuation_seed in enumerate(entry["branch_continuation_seeds_by_mask"]):
+                held = tuple(index for index in range(3) if mask & (1 << index))
+                record = {**base, "record_type": "branch", "mask": mask,
+                    "held_indices": list(held), "continuation_seed": continuation_seed,
+                    "policy_calls": 0, "inactive_held_indices": [], "decisions": [],
+                    "status": "unstarted", "bad_targets": {target: None for target in TARGETS},
+                    "trace": None, "explanation": None}
+                if budget.calls < budget.max_calls:
+                    replay = replay_decision_coalition(factual, budget, held_indices=held,
+                        continuation_seed=continuation_seed, coalition_game=game)
+                    record.update(status=replay.status, summary=replay.summary(),
+                        decisions=to_dict(replay.decisions), policy_calls=replay.policy_calls,
+                        inactive_held_indices=list(replay.inactive_held_indices))
+                    if replay.episode is not None:
+                        outcome = episode_outcome(replay.episode)
+                        record.update(trace=replay.episode.trace.to_dict(),
+                            explanation=replay.episode.explanation.to_dict(),
+                            bad_targets={target: (None if outcome.target_value(target) is None else
+                                                 int(not outcome.target_value(target))) for target in TARGETS})
+                        _line(gold, {**base, "record_type": "branch", "mask": mask,
+                            "seed": replay.episode.seed, "config": to_dict(replay.episode.config),
+                            "records": to_dict(replay.episode.ground_truth)})
+                record.update(budget_calls_after=budget.calls, budget_max_calls=budget.max_calls)
+                _line(evidence, record)
+                retained[name].append(record)
+    summary = {"design": "exact deterministic-mixture world enumeration",
+        "cases": {name: _summarize_case(INTERACTION_MECHANISMS[name], retained[name]) for name in names},
+        "actual_policy_calls": sum(record["policy_calls"] for rows in retained.values() for record in rows),
+        "additional_reference_policy_calls": 0,
+        "completed": True}
+    _write(root / "summary.json", summary)
+    text = ["# Refund interaction enumeration", "", "This artifact enumerates four deterministic fresh-choice components, all eight held masks, and both explicitly named games. It is not a set of live stochastic samples.", "",
+        "The factual refund, retry and final stop are planted. All targets come from actual payment readback; evaluator records are stored separately.", "",
+        "| Case | Game | Consequence shares | Interaction |", "| --- | --- | --- | --- |"]
+    for name, item in summary["cases"].items():
+        for game, result in item["games"].items():
+            target = result["targets"]["consequence"]
+            text.append(f"| {name} | {game} | {target['shapley_values']} | {target['selection_retry_interaction']} |")
+    text += ["", f"Actual synthetic policy calls: {summary['actual_policy_calls']}.", "",
+        "A positive invalid, unknown, failed or unstarted mixture weight refuses the numerical vector. Budget controls retain the reference law while refusing incomplete enumerations. Zero-weight components remain in the evidence but do not affect that law.", "",
+        "Run the independent auditor in `scripts/audit_refund_interactions.py` against this directory. Permutation-sampler accuracy, live-model studies, context/fault attribution and cross-domain recovery require separate experiments."]
+    (root / "README.md").write_text("\n".join(text) + "\n", encoding="utf-8", newline="\n")
+    _write(root / "manifest.json", {"package_version": __version__,
+        "completed": True, "status": "completed", "artifacts": [
+            {"path": path.relative_to(root).as_posix(),
+             "sha256": sha256(path.read_bytes()).hexdigest(), "bytes": path.stat().st_size}
+            for path in sorted(root.rglob("*")) if path.is_file() and path != root / "manifest.json"]})
+    return summary
+
+
+def main(argv=None):
+    import argparse
+
+    parser = argparse.ArgumentParser(description=__doc__)
+    parser.add_argument("--output", required=True)
+    parser.add_argument("--source-revision", required=True)
+    parser.add_argument("--seed", type=int, default=4_000_000)
+    parser.add_argument("--mechanism", action="append", choices=tuple(INTERACTION_MECHANISMS))
+    args = parser.parse_args(argv)
+    result = export_refund_interactions(args.output, source_revision=args.source_revision,
+                                       seed=args.seed, mechanisms=args.mechanism)
+    print(json.dumps({"output": str(Path(args.output).resolve()),
+                      "actual_policy_calls": result["actual_policy_calls"]}, sort_keys=True))
+
+
+if __name__ == "__main__":
+    main()

consequa_x/benchmark/interaction_mechanisms.py

@@ -0,0 +1,192 @@
+"""Public-only refund policies and independent population interaction laws.
+
+The factual refund/retry/stop is planted at three declared phase keys. Fresh
+choices either follow a seeded Bernoulli law or one explicitly named component
+of its four-point deterministic mixture. Neither policy sees evaluator truth.
+"""
+
+from dataclasses import dataclass
+import math
+import random
+from types import MappingProxyType
+
+from ..models import AssessmentStatus, ResponseStatus
+from ..policies import PolicyDecision, PolicyError, PolicyReply, PolicyRequest, validate_seed
+from .decision_coalition import validate_coalition_game
+from .payments import Fault
+from .policy_runner import MAX_TRIAL_SEED, run_policy_scenario
+from .runner import RefundContext, ScenarioConfig
+
+
+TARGETS = ("action", "consequence", "action_linked_consequence")
+COMPONENTS = ((False, False), (False, True), (True, False), (True, True))
+
+
+def _probability(value, name):
+    if type(value) not in (int, float) or not math.isfinite(value) or not 0 <= value <= 1:
+        raise ValueError(f"{name} must be a finite probability in 0..1")
+
+
+@dataclass(frozen=True)
+class RefundInteractionPolicy:
+    selection_probability: float
+    retry_probability: float
+    factual_policy_seed: int
+    fresh_selection: bool | None = None
+    fresh_retry: bool | None = None
+
+    def __post_init__(self):
+        _probability(self.selection_probability, "selection_probability")
+        _probability(self.retry_probability, "retry_probability")
+        if type(self.factual_policy_seed) is not int or not 0 <= self.factual_policy_seed <= MAX_TRIAL_SEED:
+            raise ValueError("factual_policy_seed is outside the valid world/model phase schedule")
+        if not ((self.fresh_selection is None and self.fresh_retry is None)
+                or (type(self.fresh_selection) is bool and type(self.fresh_retry) is bool)):
+            raise ValueError("fresh component choices must both be booleans or both be None")
+
+    @property
+    def metadata(self):
+        component = self.fresh_selection is not None
+        return {
+            "provider": "synthetic", "policy": "conditioned-refund-interaction", "version": "1",
+            "selection_probability": self.selection_probability,
+            "retry_probability": self.retry_probability,
+            "fresh_rule": {
+                "kind": "deterministic_mixture_component" if component else "seeded_bernoulli",
+                "selection": self.fresh_selection, "retry": self.fresh_retry,
+                "rng": None if component else "python_random.Random(model_phase_seed)",
+                "is_live_stochastic_sample": False,
+            },
+            "conditioning": {
+                "kind": "predeclared_factual_refund_retry_stop_intervention",
+                "naturally_sampled_factual": False,
+                "reserved_model_phase_seeds": [self.factual_policy_seed * 6 + i for i in range(3)],
+                "operations": ["refund", "retry", "stop"],
+            },
+            "hidden_evidence_inputs": False,
+        }
+
+    def decide(self, request: PolicyRequest, *, seed: int):
+        if not isinstance(request, PolicyRequest):
+            raise PolicyError("Expected a PolicyRequest")
+        validate_seed(seed)
+        base = self.factual_policy_seed * 6
+        if seed in (base, base + 1, base + 2):
+            operation = ("refund", "retry", "stop")[seed - base]
+            source = "reserved_factual_intervention"
+        elif request.stage == "select":
+            selected = (random.Random(seed).random() < self.selection_probability
+                        if self.fresh_selection is None else self.fresh_selection)
+            operation = "refund" if selected else "stop"
+            source = self.metadata["fresh_rule"]["kind"]
+        elif request.responses[-1].status is ResponseStatus.TIMEOUT and request.attempts_remaining:
+            retry = (random.Random(seed).random() < self.retry_probability
+                     if self.fresh_retry is None else self.fresh_retry)
+            operation = "retry" if retry else "stop"
+            source = self.metadata["fresh_rule"]["kind"]
+        else:
+            operation, source = "stop", "fixed_final_stop"
+        return PolicyReply(PolicyDecision(operation, AssessmentStatus.UNKNOWN,
+            "Transparent fixture choice from the declared public-stage rule."),
+            {"seed": seed, "decision_source": source})
+
+
+@dataclass(frozen=True)
+class RefundInteractionMechanism:
+    name: str
+    selection_probability: float = .5
+    retry_probability: float = .5
+    use_idempotency: bool = False
+    include_provenance: bool = True
+    read_lag_ms: int = 0
+    max_calls: int = 100
+
+    def __post_init__(self):
+        if type(self.name) is not str or not self.name.strip():
+            raise ValueError("name must be a nonempty string")
+        _probability(self.selection_probability, "selection_probability")
+        _probability(self.retry_probability, "retry_probability")
+        if type(self.use_idempotency) is not bool or type(self.include_provenance) is not bool:
+            raise ValueError("idempotency and provenance flags 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")
+        if type(self.max_calls) is not int or self.max_calls < 3:
+            raise ValueError("max_calls must leave three calls for the factual capture")
+
+    def make_policy(self, *, factual_policy_seed, component=None):
+        if component is not None and component not in COMPONENTS:
+            raise ValueError("component must be one of the four Boolean choice pairs")
+        return RefundInteractionPolicy(self.selection_probability, self.retry_probability,
+            factual_policy_seed, *(component if component is not None else (None, None)))
+
+    def scenario_config(self):
+        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, policy_seed):
+        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 component_weights(self):
+        p, q = self.selection_probability, self.retry_probability
+        return tuple((p if selected else 1 - p) * (q if retry else 1 - q)
+                     for selected, retry in COMPONENTS)
+
+    def analytic_reference(self, *, coalition_game="on_reach"):
+        """Closed-form population law, independent of rollout or sampled keys.
+
+        An unknown or invalid component of positive mass refuses a coalition;
+        no conditioning on known, valid, or reached branches is performed.
+        """
+        validate_coalition_game(coalition_game)
+        p, q = self.selection_probability, self.retry_probability
+        selected = [1. if mask & 1 else p for mask in range(8)]
+        retry = [1. if mask & 2 else q for mask in range(8)]
+        valid = [1. if coalition_game == "on_reach" else (
+            selected[mask] * retry[mask] if mask & 4 else selected[mask] if mask & 2 else 1.)
+            for mask in range(8)]
+        targets = {}
+        for target in TARGETS:
+            bad = [1 - s if target == "action" or self.use_idempotency
+                   else 1 - s * (1 - r) for s, r in zip(selected, retry)]
+            unknown = [0. if target == "action" else 1. if self.read_lag_ms else (
+                (s if self.use_idempotency else s * (1 - r))
+                if target == "action_linked_consequence" and not self.include_provenance else 0.)
+                for s, r in zip(selected, retry)]
+            values = [value if valid[mask] == 1 and unknown[mask] == 0 else None
+                      for mask, value in enumerate(bad)]
+            eligible = all(value is not None for value in values)
+            if eligible:
+                if target == "action" or self.use_idempotency:
+                    shares, interaction = [-(1 - p), 0., 0.], 0.
+                else:
+                    shares = [-(1 - p) * (1 - q) / 2, (1 + p) * (1 - q) / 2, 0.]
+                    interaction = (1 - p) * (1 - q)
+            else:
+                shares, interaction = None, None
+            endpoint_eligible = values[0] is not None and values[7] is not None
+            targets[target] = {
+                "coalition_bad_rates": values, "unknown_probabilities": unknown,
+                "shapley_eligible": eligible, "shapley_values": shares,
+                "selection_retry_interaction": interaction,
+                "endpoint_eligible": endpoint_eligible,
+                "endpoint_difference": values[7] - values[0] if endpoint_eligible else None,
+                "reason": None if eligible else "positive invalid or unknown population mass",
+            }
+        return {"name": self.name, "coalition_game": coalition_game, "decision_count": 3,
+                "selection_probability": p, "retry_probability": q,
+                "population_not_finite_seed_claim": True,
+                "coalition_valid_probabilities": valid, "targets": targets}
+
+
+INTERACTION_MECHANISMS = MappingProxyType({item.name: item for item in (
+    RefundInteractionMechanism("refund-p50-q50"),
+    RefundInteractionMechanism("refund-p20-q80", .2, .8),
+    RefundInteractionMechanism("refund-p80-q20", .8, .2),
+    RefundInteractionMechanism("refund-p100-q100", 1., 1.),
+    RefundInteractionMechanism("idempotent-p50-q50", use_idempotency=True),
+    RefundInteractionMechanism("unknown-provenance-p50-q50", include_provenance=False),
+    RefundInteractionMechanism("lagged-readback-p50-q50", read_lag_ms=1000),
+    RefundInteractionMechanism("budget-p50-q50", max_calls=4),
+)})