hypermind 0.11.0__py3-none-any.whl

hypermind/mind/integration.py

@@ -0,0 +1,190 @@
+"""Bind a Deliberator to HyperMindAgent without editing agent.py.
+
+We attach methods at import-time:
+    agent.bind_deliberator(deliberator)  → store reference
+    agent.pursue(goal)                   → adds goal to bound deliberator
+    agent.tick()                         → advance the deliberator one step
+    agent.deliberator                    → get the bound deliberator (or None)
+    agent.plan_and_act(goal)             → T4-03 plan-and-act primitive
+
+This module is imported by ``hypermind.__init__`` so the API is
+available the moment a user does ``import hypermind``. Agents
+constructed without ``bind_deliberator`` behave exactly as before
+(zero behavioural change to existing tests).
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hypermind.mind.deliberator import Deliberator, DeliberatorTick
+from hypermind.mind.goals import Goal, GoalStatus
+
+if TYPE_CHECKING:
+    from hypermind.agent import HyperMindAgent
+    from hypermind.workflow.engine import WorkflowState
+
+_ATTR = "_mind_deliberator"
+
+
+def bind_deliberator(self: HyperMindAgent, deliberator: Deliberator) -> Deliberator:
+    setattr(self, _ATTR, deliberator)
+    return deliberator
+
+
+def get_deliberator(self: HyperMindAgent) -> Deliberator | None:
+    return getattr(self, _ATTR, None)
+
+
+def pursue(self: HyperMindAgent, goal: Goal) -> GoalStatus:
+    delib = get_deliberator(self)
+    if delib is None:
+        # Auto-bind a default deliberator the first time pursue() is called.
+        delib = Deliberator(self)
+        bind_deliberator(self, delib)
+    return delib.pursue(goal)
+
+
+async def tick(self: HyperMindAgent) -> DeliberatorTick:
+    delib = get_deliberator(self)
+    if delib is None:
+        raise RuntimeError(
+            "tick() requires a bound Deliberator.\n"
+            "  Hint: agent.bind_deliberator(Deliberator(agent, policies=[...])) first, "
+            "or call agent.pursue(goal) to auto-bind a default deliberator."
+        )
+    return await delib.tick()
+
+
+async def plan_and_act(
+    self: HyperMindAgent,
+    goal: Goal,
+    *,
+    executors: dict[str, Any] | None = None,
+    max_replans: int = 1,
+) -> WorkflowState:
+    """T4-03 plan-and-act primitive — decompose goal → Plan → Workflow → run.
+
+    1. Use :class:`InformationGainPlanner` to decompose ``goal`` into a
+       :class:`Plan` (a :class:`PlanDAG` with one node per step).
+    2. Compile :meth:`Plan.to_workflow` and register the resulting body
+       as a one-shot ``@workflow`` so :class:`Workflow.run` can drive it.
+    3. Run via ``await Workflow.run``. If a :class:`RepairOnDispute`
+       observation arrives mid-run via the bound deliberator, the
+       :class:`DefaultRepairPolicy` produces a replan; this method
+       catches the replan and re-runs (up to ``max_replans`` times).
+
+    ``executors`` lets callers inject per-node coroutines; structural
+    nodes without an executor become no-op steps that record their
+    payload (so a bare goal still produces a runnable workflow).
+    """
+    from hypermind.mind.active import CandidateQuestion, InformationGainPlanner
+    from hypermind.workflow.engine import Workflow
+    from hypermind.workflow.engine import workflow as workflow_decorator
+    from hypermind.workflow.plan import Plan, PlanDAG, PlanNode
+    from hypermind.workflow.repair import DefaultRepairPolicy, WorkflowDisputeContext
+
+    planner = InformationGainPlanner()
+    # Decompose goal into a small candidate question set; one node per
+    # candidate plus a final synthesis node. The scoring is informational
+    # only — the planner has already shaped the DAG topology.
+    candidates = [
+        CandidateQuestion(
+            qid=f"q-{i}",
+            topic=goal.topic,
+            expected_posterior=0.5,
+        )
+        for i in range(2)
+    ]
+    ranked = planner.rank(candidates)
+
+    dag = PlanDAG()
+    dag.add_node(
+        PlanNode(
+            node_id="goal_root",
+            kind="goal",
+            payload={
+                "topic": goal.topic,
+                "target_confidence": goal.target_confidence,
+                "rule_id": "MIND-PLAN-AND-ACT",
+            },
+        )
+    )
+    prev = "goal_root"
+    for q in ranked:
+        node_id = f"act-{q.qid}"
+        dag.add_node(
+            PlanNode(
+                node_id=node_id,
+                kind="action",
+                payload={"qid": q.qid, "topic": q.topic},
+            )
+        )
+        dag.add_edge(prev, node_id, "depends_on")
+        prev = node_id
+    dag.add_node(
+        PlanNode(
+            node_id="synthesise",
+            kind="fanin",
+            payload={"rule_id": "MIND-PLAN-SYNTH"},
+        )
+    )
+    dag.add_edge(prev, "synthesise", "depends_on")
+
+    plan = Plan(
+        dag=dag,
+        executors=dict(executors or {}),
+        name=f"plan-and-act-{goal.goal_id}",
+    )
+
+    body = plan.to_workflow()
+    # Register under a unique name so multiple pursue() calls don't clash.
+    workflow_decorator(name=plan.name)(body)
+
+    # Run; on dispute observation in the deliberator, replan once.
+    state: WorkflowState = await Workflow.run(body)
+
+    delib = get_deliberator(self)
+    replans = 0
+    while delib is not None and replans < max_replans:
+        repair_obs = next(
+            (
+                o
+                for o in delib._observations  # type: ignore[attr-defined]
+                if o.get("kind") == "dispute_close" and o.get("workflow_id") == state.workflow_id
+            ),
+            None,
+        )
+        if repair_obs is None:
+            break
+        # A dispute close arrived for this workflow — emit a fresh plan.
+        repair = DefaultRepairPolicy()
+        outcome = type(
+            "_O",
+            (),
+            {
+                "final_state": repair_obs.get("final_state", "UNRESOLVED_PARTITION"),
+                "target_kid": repair_obs.get("target_kid", b""),
+            },
+        )()
+        repair_plan = repair.repair(WorkflowDisputeContext(workflow_state=state, outcome=outcome))
+        repair_body = repair_plan.to_workflow()
+        workflow_decorator(name=repair_plan.name)(repair_body)
+        state = await Workflow.run(repair_body)
+        replans += 1
+
+    return state
+
+
+def install() -> None:
+    """Attach the mind methods onto HyperMindAgent. Idempotent."""
+    from hypermind.agent import HyperMindAgent
+
+    if getattr(HyperMindAgent, "_mind_installed", False):
+        return
+    HyperMindAgent.bind_deliberator = bind_deliberator  # type: ignore[attr-defined]
+    HyperMindAgent.pursue = pursue  # type: ignore[attr-defined]
+    HyperMindAgent.tick = tick  # type: ignore[attr-defined]
+    HyperMindAgent.plan_and_act = plan_and_act  # type: ignore[attr-defined]
+    HyperMindAgent.deliberator = property(get_deliberator)  # type: ignore[attr-defined]
+    HyperMindAgent._mind_installed = True  # type: ignore[attr-defined]

hypermind/mind/mediator.py

@@ -0,0 +1,74 @@
+"""Deterministic mediator selection (closes ROADMAP gap 6).
+
+When a dispute reaches COUNTER state without resolution, a mediator is
+selected from a verifiable random pool. The selection is a verifiable
+random function over (dispute_kid, sorted(eligible_pool)): every
+participant computes the same selection, so deadlock is impossible
+without collusion exceeding the eligible pool's honest majority.
+
+VRF here is HMAC-SHA256 (deterministic, publicly verifiable given
+inputs). Future versions may upgrade to Ed25519-VRF once a vetted
+Python implementation lands; the API does not change.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import hmac
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass
+
+from hypermind.knowledge.reputation import ReputationKernel
+
+
+@dataclass(frozen=True)
+class MediatorSelector:
+    topic: str
+    min_reputation: float = 0.6
+    min_observations: int = 30
+
+    def eligible(
+        self,
+        candidates: Iterable[bytes],
+        *,
+        reputation: ReputationKernel,
+        exclude: Iterable[bytes] = (),
+    ) -> list[bytes]:
+        excluded = {bytes(k) for k in exclude}
+        out: list[bytes] = []
+        for kid in candidates:
+            kid_b = bytes(kid)
+            if kid_b in excluded:
+                continue
+            snap = reputation.snapshot(kid_b, self.topic)
+            if snap.score < self.min_reputation:
+                continue
+            if snap.n_observations < self.min_observations:
+                continue
+            out.append(kid_b)
+        # Stable order — required for determinism.
+        out.sort()
+        return out
+
+
+def select_mediator(
+    *,
+    dispute_kid: bytes,
+    eligible_pool: Sequence[bytes],
+) -> bytes:
+    """VRF-style deterministic pick from a sorted eligible pool.
+
+    ``dispute_kid`` MUST be 32 bytes (the SHA-256 kid of the dispute
+    record); the eligible pool MUST be the canonical sorted output of
+    ``MediatorSelector.eligible``. Identical inputs across nodes ⇒
+    identical mediator.
+    """
+    if len(dispute_kid) != 32:
+        raise ValueError("dispute_kid must be 32 bytes")
+    if not eligible_pool:
+        raise ValueError("eligible_pool must be non-empty")
+    pool = sorted(set(bytes(k) for k in eligible_pool))
+    # HMAC the concatenated pool with the dispute_kid as the key.
+    mac = hmac.new(dispute_kid, b"".join(pool), hashlib.sha256).digest()
+    idx = int.from_bytes(mac, "big") % len(pool)
+    return pool[idx]

hypermind/mind/memory_store.py

@@ -0,0 +1,129 @@
+"""Per-agent private memory over the RelataDB Memory API (integration P1).
+
+This is the *unsigned* half of the storage story (path b). Where
+:class:`~hypermind.storage.relata.RelataBackend` persists the verifiable ledger
+(signed claims, disputes, reputation, Merkle log), a ``RelataMemoryStore`` is an
+agent's private scratchpad of learnings and experiences — bi-temporal,
+provenance-stamped, and recallable, but **not** part of the federation ledger.
+
+Scoping mirrors the ledger backend:
+
+  * namespace  → tenant   (``X-Organization-Id`` via ``extra_headers``)
+  * agent kid  → session  (``session_id`` — per-agent memory partition)
+
+The ``relata`` SDK is imported lazily inside :meth:`open`, so this module imports
+without the optional ``hypermind[relata]`` extra. Tests inject ``memory_factory``.
+
+Citation bridge: :func:`sources_from_memory` turns memory ids into PROV-O
+provenance descriptors suitable to embed in a signed claim payload under a
+``"sources"`` key. Note this is deliberately *separate* from a claim's ``cites``
+field — ``cites`` is the intra-federation claim-kid DAG (walked by
+``CitationGraph`` with a cycle check); ``sources`` are external evidence
+references (Relata memory ids + provenance), which are not claim kids.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from hypermind.wire import Kid
+
+_PURPOSE = "agent_notes"
+
+# Returns an object exposing add()/search()/justify()/close() — i.e. relata.Memory.
+MemoryFactory = Callable[[], Any]
+
+
+class RelataMemoryStore:
+    """One agent's private memory. Bound to (server, namespace, agent kid)."""
+
+    def __init__(
+        self,
+        base_url: str,
+        *,
+        namespace_id: str,
+        agent_kid: Kid | bytes,
+        purpose: str = _PURPOSE,
+        bearer_token: str | None = None,
+        memory_factory: MemoryFactory | None = None,
+    ) -> None:
+        self._url = base_url
+        self._ns = namespace_id
+        self._session = bytes(agent_kid).hex()
+        self._purpose = purpose
+        self._tok = bearer_token
+        self._factory = memory_factory
+        self._m: Any = None
+
+    def open(self) -> None:
+        if self._m is not None:
+            return
+        if self._factory is not None:
+            self._m = self._factory()
+        else:  # pragma: no cover - requires the optional `relata` SDK + live server
+            from relata import Memory
+
+            self._m = Memory(
+                self._url,
+                purpose=self._purpose,
+                bearer_token=self._tok,
+                session_id=self._session,  # per-agent partition
+                extra_headers={"X-Organization-Id": self._ns},  # tenant isolation
+            )
+
+    def close(self) -> None:
+        if self._m is not None:
+            self._m.close()
+            self._m = None
+
+    def _require(self) -> Any:
+        if self._m is None:
+            raise RuntimeError("RelataMemoryStore used before open()")
+        return self._m
+
+    # ---- verbs ----------------------------------------------------------
+
+    def remember(
+        self, content: str, *, confidence: float = 1.0, memory_class: str = "semantic"
+    ) -> str:
+        """Store a learning/experience; return its memory id."""
+        return str(self._require().add(content, confidence=confidence, memory_class=memory_class))
+
+    def remember_batch(
+        self,
+        items: "list[str | dict]",
+        *,
+        session_id: str | None = None,
+    ) -> list[str]:
+        """Store many learnings in one request; return their ids in order.
+
+        Each item is a ``str`` (content only) or a ``dict`` with ``content``
+        and optional ``confidence`` / ``memory_class`` / ``purpose``.
+        Delegates to ``POST /memory/remember/batch`` — amortises per-request
+        overhead and the index flush across the whole batch.
+        """
+        return list(self._require().add_batch(items, session_id=session_id))
+
+    def recall(self, query: str, *, top_k: int = 5, as_of: str | None = None) -> list[dict]:
+        """Ranked recall (confidence × recency × relevance).
+
+        Pass ``as_of`` (a timestamp) for bi-temporal recall — "what did this
+        agent know at T?".
+        """
+        return list(self._require().search(query, top_k=top_k, as_of=as_of))
+
+    def justify(self, memory_id: str) -> dict:
+        """Return the PROV-O provenance chain for ``memory_id``."""
+        return dict(self._require().justify(memory_id))
+
+
+def sources_from_memory(store: RelataMemoryStore, memory_ids: list[str]) -> list[dict]:
+    """Resolve memory ids into provenance descriptors for a claim payload.
+
+    Embed the result under a ``"sources"`` key in a ``publish_claim`` payload to
+    give a signed research output verifiable citations back to the evidence the
+    agent used — "no source = not in the output".
+    """
+    return [{"memory_id": mid, "provenance": store.justify(mid)} for mid in memory_ids]

hypermind/mind/policy.py

@@ -0,0 +1,307 @@
+"""ActionPolicy — pure decisions about what an agent should do next.
+
+Policies are stateless functions over a PolicyContext. They emit an
+ActionDecision (or None for "no action this tick"). The Deliberator
+collects decisions from all bound policies and picks the highest-priority
+one for dispatch.
+
+Built-ins:
+    PublishWhenConfident     — auto-publish when posterior crosses threshold
+    ConsultOnDisagreement    — auto-consult when subscribed claims diverge
+    DisputeOnContradiction   — auto-dispute when peer contradicts and rep gap > δ
+    CheckpointOnSignalGain   — auto-checkpoint when working_memory KL > threshold
+    LeverageCap              — guard wrapping any policy: bound action impact
+                               by historical Brier (anti calibration-laundering)
+
+Every Decision carries a ``rule_id`` matching the structured-refusal
+contract in src/hypermind/rule_ids.py — observability + governance live
+on this id.
+"""
+
+from __future__ import annotations
+
+import math
+from collections.abc import Sequence
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+
+class ActionKind(StrEnum):
+    PUBLISH = "publish"
+    CONSULT = "consult"
+    DISPUTE = "dispute"
+    CHECKPOINT = "checkpoint"
+    INTENT = "intent"  # broadcast a mind/intent record
+    DISSENT = "dissent"  # broadcast a mind/dissent record
+    NOOP = "noop"
+
+
+@dataclass(frozen=True)
+class PolicyContext:
+    """Snapshot of relevant agent state at a single deliberation tick.
+
+    Frozen — policies must not mutate. The Deliberator builds one fresh
+    each tick from the live agent.
+    """
+
+    topic: str
+    target_confidence: float
+    working_memory: dict[str, Any]
+    own_brier: float | None = None
+    own_reputation: float | None = None
+    recent_observations: tuple[dict[str, Any], ...] = ()  # claims seen on the topic
+    last_action: str | None = None
+    last_checkpoint_posterior: float | None = None
+    consult_in_flight: bool = False
+
+
+@dataclass(frozen=True)
+class ActionDecision:
+    kind: ActionKind
+    rule_id: str
+    priority: int  # higher wins when multiple policies fire
+    payload: dict[str, Any] = field(default_factory=dict)
+    reason: str = ""
+
+
+class ActionPolicy:
+    """Base class — subclass and implement ``decide``.
+
+    Subclasses MUST be pure: same context → same decision.
+    """
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:  # pragma: no cover - abstract
+        raise NotImplementedError
+
+
+class NoOpPolicy(ActionPolicy):
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        return None
+
+
+# -----------------------------------------------------------------------
+# Built-in policies
+# -----------------------------------------------------------------------
+
+
+@dataclass
+class PublishWhenConfident(ActionPolicy):
+    """Publish a claim once the posterior on the goal topic crosses the threshold.
+
+    Only fires when (a) we have a posterior for the goal topic AND (b)
+    we have not just published in the last tick (avoids storms). The
+    SelfReflector may ratchet ``threshold`` up if past publishes get
+    disputed too often.
+    """
+
+    threshold: float = 0.8
+    priority: int = 50
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        posteriors = ctx.working_memory.get("posteriors", {})
+        score = posteriors.get(ctx.topic)
+        if score is None:
+            return None
+        effective = max(self.threshold, ctx.target_confidence)
+        if score < effective:
+            return None
+        if ctx.last_action == "publish":
+            return None
+        return ActionDecision(
+            kind=ActionKind.PUBLISH,
+            rule_id="MIND-PUBLISH-CONFIDENT",
+            priority=self.priority,
+            payload={"posterior": score, "threshold": effective},
+            reason=f"posterior {score:.3f} ≥ threshold {effective:.3f}",
+        )
+
+
+@dataclass
+class ConsultOnDisagreement(ActionPolicy):
+    """Trigger a consult when subscribed peers disagree on the topic.
+
+    Disagreement = stdev of recent peer posteriors > divergence.
+    """
+
+    divergence: float = 0.3
+    min_observations: int = 2
+    priority: int = 40
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        if ctx.consult_in_flight:
+            return None
+        scores = [
+            float(o["posterior"])
+            for o in ctx.recent_observations
+            if o.get("topic") == ctx.topic and "posterior" in o
+        ]
+        if len(scores) < self.min_observations:
+            return None
+        mean = sum(scores) / len(scores)
+        var = sum((s - mean) ** 2 for s in scores) / len(scores)
+        std = math.sqrt(var)
+        if std < self.divergence:
+            return None
+        return ActionDecision(
+            kind=ActionKind.CONSULT,
+            rule_id="MIND-CONSULT-DISAGREEMENT",
+            priority=self.priority,
+            payload={"observed_stdev": std, "divergence_threshold": self.divergence},
+            reason=f"peer posterior stdev {std:.3f} ≥ {self.divergence:.3f}",
+        )
+
+
+@dataclass
+class DisputeOnContradiction(ActionPolicy):
+    """Auto-dispute a peer claim when it contradicts ours by a wide margin.
+
+    Fires when we have an own posterior on the topic and a recent peer
+    claim has the opposite verdict (one above 0.5, the other below) by
+    at least ``min_gap`` AND our reputation gap (own − peer) ≥
+    ``min_rep_delta``. Avoids low-rep agents picking fights with
+    high-rep agents.
+    """
+
+    min_gap: float = 0.4
+    min_rep_delta: float = 0.15
+    priority: int = 60
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        own_score = (ctx.working_memory.get("posteriors") or {}).get(ctx.topic)
+        if own_score is None or ctx.own_reputation is None:
+            return None
+        for obs in ctx.recent_observations:
+            if obs.get("topic") != ctx.topic:
+                continue
+            peer_score = obs.get("posterior")
+            peer_rep = obs.get("reputation")
+            target_kid = obs.get("kid")
+            if peer_score is None or peer_rep is None or target_kid is None:
+                continue
+            # Opposite verdicts only.
+            if (own_score - 0.5) * (peer_score - 0.5) >= 0:
+                continue
+            if abs(own_score - peer_score) < self.min_gap:
+                continue
+            if (ctx.own_reputation - peer_rep) < self.min_rep_delta:
+                continue
+            return ActionDecision(
+                kind=ActionKind.DISPUTE,
+                rule_id="MIND-DISPUTE-CONTRADICTION",
+                priority=self.priority,
+                payload={
+                    "target_kid": target_kid,
+                    "own_score": own_score,
+                    "peer_score": peer_score,
+                    "rep_delta": ctx.own_reputation - peer_rep,
+                },
+                reason=(
+                    f"contradiction gap {abs(own_score - peer_score):.2f}, "
+                    f"rep advantage {(ctx.own_reputation - peer_rep):.2f}"
+                ),
+            )
+        return None
+
+
+@dataclass
+class CheckpointOnSignalGain(ActionPolicy):
+    """Auto-checkpoint when working_memory has shifted enough since last seal.
+
+    Uses Bernoulli KL divergence on the topic's posterior between the
+    last checkpoint and now. Cheap, scale-invariant, and intuitive
+    ("posterior moved noticeably" → seal a snapshot).
+    """
+
+    kl_threshold: float = 0.1
+    priority: int = 30
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        score = (ctx.working_memory.get("posteriors") or {}).get(ctx.topic)
+        if score is None:
+            return None
+        if ctx.last_checkpoint_posterior is None:
+            return ActionDecision(
+                kind=ActionKind.CHECKPOINT,
+                rule_id="MIND-CHECKPOINT-FIRST",
+                priority=self.priority,
+                payload={"posterior": score},
+                reason="initial checkpoint",
+            )
+        kl = _bernoulli_kl(score, ctx.last_checkpoint_posterior)
+        if kl < self.kl_threshold:
+            return None
+        return ActionDecision(
+            kind=ActionKind.CHECKPOINT,
+            rule_id="MIND-CHECKPOINT-SIGNAL-GAIN",
+            priority=self.priority,
+            payload={"posterior": score, "kl": kl},
+            reason=f"KL {kl:.3f} ≥ threshold {self.kl_threshold:.3f}",
+        )
+
+
+def _bernoulli_kl(p: float, q: float) -> float:
+    """KL(Bern(p) || Bern(q)). Clamps to a tiny eps to avoid log(0)."""
+    eps = 1e-9
+    p = min(max(p, eps), 1.0 - eps)
+    q = min(max(q, eps), 1.0 - eps)
+    return p * math.log(p / q) + (1 - p) * math.log((1 - p) / (1 - q))
+
+
+# -----------------------------------------------------------------------
+# Adversarial guard: LeverageCap
+# -----------------------------------------------------------------------
+
+
+@dataclass
+class LeverageCap(ActionPolicy):
+    """Wrap an inner policy and veto/attenuate its publish actions.
+
+    Protects against calibration-laundering (failure-modes.md:15): an
+    agent with great historical reputation but a known bad calibration
+    on this topic should not be able to broadcast a high-leverage claim.
+
+    The cap is a multiplicative factor applied to *claim weight* (passed
+    into the publish payload as ``leverage_factor``). Downstream consult
+    aggregation may use this when computing influence. ``own_brier``
+    above ``brier_ceiling`` triggers the cap.
+    """
+
+    inner: ActionPolicy
+    brier_ceiling: float = 0.25
+    min_leverage: float = 0.2
+
+    def decide(self, ctx: PolicyContext) -> ActionDecision | None:
+        decision = self.inner.decide(ctx)
+        if decision is None:
+            return None
+        if decision.kind is not ActionKind.PUBLISH:
+            return decision
+        brier = ctx.own_brier
+        if brier is None or brier <= self.brier_ceiling:
+            return decision
+        # Linear interpolation: brier=ceiling → 1.0; brier=2*ceiling → min_leverage.
+        ratio = (brier - self.brier_ceiling) / max(self.brier_ceiling, 1e-9)
+        leverage = max(self.min_leverage, 1.0 - ratio)
+        new_payload = dict(decision.payload)
+        new_payload["leverage_factor"] = leverage
+        new_payload["leverage_reason"] = "MIND-LEVERAGE-CAP"
+        return ActionDecision(
+            kind=decision.kind,
+            rule_id="MIND-LEVERAGE-CAP",
+            priority=decision.priority,
+            payload=new_payload,
+            reason=(
+                f"{decision.reason}; leverage capped to {leverage:.2f} "
+                f"(brier {brier:.3f} > {self.brier_ceiling:.3f})"
+            ),
+        )
+
+
+def select_top_decision(decisions: Sequence[ActionDecision | None]) -> ActionDecision | None:
+    """Pick the highest-priority decision; ties broken by rule_id sort."""
+    live = [d for d in decisions if d is not None]
+    if not live:
+        return None
+    live.sort(key=lambda d: (-d.priority, d.rule_id))
+    return live[0]