hypermind 0.11.0__py3-none-any.whl

hypermind/knowledge/rekor.py

@@ -0,0 +1,173 @@
+"""Sigstore Rekor read-only client + downgrade-mode submitter.
+
+ROADMAP §0.3.1 (read), §0.4.3 (write).
+
+The client is intentionally minimal: it speaks the Rekor v1 REST API
+and handles transparency-log entry lookup + RFC 6962 inclusion-proof
+verification. Any heavier integration (key trust roots, fulcio cert
+chain validation) is deferred to v0.7 alongside the rest of the
+sigstore trust-bundle work.
+
+``httpx`` is a soft dependency — imports are lazy so the SDK still
+loads in environments that haven't installed the ``[rekor]`` extra.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+from dataclasses import dataclass
+from typing import Any
+
+from hypermind.knowledge.transparency import (
+    PortableInclusionProof,
+    verify_inclusion,
+)
+
+
+class RekorUnavailableError(RuntimeError):
+    """Raised when ``httpx`` is not installed."""
+
+
+def _load_httpx() -> Any:
+    try:
+        import httpx
+    except ImportError as e:  # pragma: no cover - depends on env
+        raise RekorUnavailableError(
+            "Rekor integration requires `httpx`. "
+            "Install with `pip install httpx` or `pip install 'hypermind[rekor]'`."
+        ) from e
+    return httpx
+
+
+@dataclass(frozen=True)
+class RekorEntry:
+    """A single Rekor log entry, normalised across upstream API shapes."""
+
+    uuid: str
+    log_index: int
+    integrated_time: int
+    log_id: str
+    body: bytes  # base64-decoded body (the canonical entry blob)
+    inclusion_proof: PortableInclusionProof | None
+    root_hash: bytes | None
+    tree_size: int | None
+
+
+@dataclass
+class RekorClient:
+    """Read-only Sigstore Rekor client.
+
+    Construct with the public Rekor URL or a self-hosted instance::
+
+        client = RekorClient("https://rekor.sigstore.dev")
+        entry = client.lookup("e3b0c44...uuid...")
+        assert client.verify_inclusion(entry)
+    """
+
+    base_url: str = "https://rekor.sigstore.dev"
+    timeout: float = 5.0
+    transport: Any = None  # httpx.BaseTransport — for tests
+
+    def _client(self) -> Any:
+        httpx = _load_httpx()
+        kwargs: dict[str, Any] = {"base_url": self.base_url, "timeout": self.timeout}
+        if self.transport is not None:
+            kwargs["transport"] = self.transport
+        return httpx.Client(**kwargs)
+
+    # ---- read paths --------------------------------------------------
+
+    def lookup(self, uuid: str) -> RekorEntry:
+        """Fetch and parse a single Rekor entry by UUID."""
+        with self._client() as c:
+            resp = c.get(f"/api/v1/log/entries/{uuid}")
+            resp.raise_for_status()
+            body = resp.json()
+        return _parse_entry(body)
+
+    def verify_inclusion(self, entry: RekorEntry) -> bool:
+        """Verify the entry's inclusion proof against its embedded root.
+
+        Returns False (not raises) on missing or malformed proof so
+        callers can treat unverifiable entries as untrusted.
+        """
+        if entry.inclusion_proof is None or entry.root_hash is None:
+            return False
+        leaf_hash = hashlib.sha256(b"\x00" + entry.body).digest()
+        return verify_inclusion(leaf_hash, entry.inclusion_proof, entry.root_hash)
+
+    # ---- write paths (ROADMAP §0.4.3) --------------------------------
+
+    def submit_downgrade(self, signed_statement: Any) -> str:
+        """Submit a HyperMind ``SignedStatement`` to Rekor as cross-anchor
+        evidence.
+
+        Used when an operator wants Sigstore-anchored proof that a
+        statement existed at the submission time. Returns the Rekor UUID
+        of the new entry. The "downgrade" terminology reflects that the
+        HyperMind log is the canonical primary source — Rekor is a
+        secondary anchor used for cross-ecosystem auditability.
+        """
+        try:
+            payload = signed_statement.to_bytes()
+        except AttributeError:
+            payload = bytes(signed_statement)
+        body_b64 = base64.b64encode(payload).decode("ascii")
+        proposed = {
+            "kind": "hypermind",
+            "apiVersion": "0.0.1",
+            "spec": {"content": body_b64},
+        }
+        with self._client() as c:
+            resp = c.post("/api/v1/log/entries", json=proposed)
+            resp.raise_for_status()
+            data = resp.json()
+        # Rekor returns {uuid: entry_dict}
+        if isinstance(data, dict) and len(data) == 1:
+            return next(iter(data.keys()))
+        raise RuntimeError(f"unexpected Rekor response: {data!r}")
+
+
+def _parse_entry(body: dict[str, Any]) -> RekorEntry:
+    """Normalise a Rekor v1 entries response into a :class:`RekorEntry`.
+
+    Rekor returns ``{uuid: {body, integratedTime, logIndex, ...}}``; we
+    accept either the wrapped form or a single-entry dict.
+    """
+    if not isinstance(body, dict):
+        raise ValueError(f"unexpected entry shape: {type(body)}")
+    if len(body) == 1 and isinstance(next(iter(body.values())), dict):
+        uuid, raw = next(iter(body.items()))
+    else:
+        uuid = body.get("uuid", "")
+        raw = body
+    inc = raw.get("verification", {}).get("inclusionProof", {}) or {}
+    proof: PortableInclusionProof | None = None
+    root_hash: bytes | None = None
+    tree_size: int | None = None
+    if inc:
+        try:
+            audit_path = tuple(bytes.fromhex(h) for h in inc.get("hashes", []))
+            leaf_index = int(inc["logIndex"])
+            tree_size = int(inc["treeSize"])
+            root_hash = bytes.fromhex(inc["rootHash"])
+            proof = PortableInclusionProof(
+                audit_path=audit_path,
+                leaf_index=leaf_index,
+                tree_size=tree_size,
+            )
+        except (KeyError, ValueError):
+            proof = None
+    body_b64 = raw.get("body", "")
+    body_bytes = base64.b64decode(body_b64) if body_b64 else b""
+    return RekorEntry(
+        uuid=uuid,
+        log_index=int(raw.get("logIndex", 0)),
+        integrated_time=int(raw.get("integratedTime", 0)),
+        log_id=str(raw.get("logID", "")),
+        body=body_bytes,
+        inclusion_proof=proof,
+        root_hash=root_hash,
+        tree_size=tree_size,
+    )

hypermind/knowledge/reputation.py

@@ -0,0 +1,364 @@
+"""Reputation kernel.
+
+v0.1 ships per-(agent, topic) reputation with smooth slashing and lazy
+decay. v0.2 will swap the elicitation/aggregation rule for Correlated
+Agreement peer-prediction (Wei-Chen Cycle 2 §1) without touching this
+interface.
+
+Reputation is stored as a moving Beta posterior:
+  - α = correct outcomes + 1 (Laplace prior)
+  - β = incorrect outcomes + 1
+  - mean = α / (α + β) ∈ (0, 1)
+
+Slashing:  α' = α · (1 - λ),  β' = β + μ  on a confirmed bad outcome
+Decay:     half-life H_T (default 180d) on the (α + β - 2) above-prior mass
+
+Wire-version-0 normative defaults (closes spec/06-conformance.md gap #13):
+    λ = 0.02, μ = 0.015, threshold = 0.5, H_T = 180 days
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import time
+from collections import deque
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from hypermind.transport.bus import GossipBus
+
+LAMBDA_DEFAULT = 0.02
+MU_DEFAULT = 0.015
+THRESHOLD_DEFAULT = 0.5
+H_T_DEFAULT_DAYS = 180
+STALENESS_WINDOW_MS_DEFAULT = 90 * 24 * 60 * 60 * 1000  # 90 days
+LAMBDA_STALENESS_DEFAULT = 0.005
+
+
+@dataclass
+class ReputationSnapshot:
+    agent_id: bytes
+    topic: str
+    score: float
+    n_observations: int
+    last_updated_ms: int
+    momentum_z: float = 0.0  # A-MOMENTUM-DETECTION
+
+
+@dataclass
+class _BetaPosterior:
+    alpha: float = 1.0
+    beta: float = 1.0
+    last_update_ms: int = field(default_factory=lambda: int(time.time() * 1000))
+    last_score: float = 0.5
+    score_history: deque = field(default_factory=lambda: deque(maxlen=200))
+
+
+class ReputationKernel:
+    """Per-(agent, topic) reputation with bounded slashing + lazy decay."""
+
+    def __init__(
+        self,
+        *,
+        lam: float = LAMBDA_DEFAULT,
+        mu: float = MU_DEFAULT,
+        threshold: float = THRESHOLD_DEFAULT,
+        half_life_days: int = H_T_DEFAULT_DAYS,
+        staleness_window_ms: int = STALENESS_WINDOW_MS_DEFAULT,
+        lambda_staleness: float = LAMBDA_STALENESS_DEFAULT,
+    ) -> None:
+        self.lam = lam
+        self.mu = mu
+        self.threshold = threshold
+        self.half_life_days = half_life_days
+        self.staleness_window_ms = staleness_window_ms
+        self.lambda_staleness = lambda_staleness
+        self._posteriors: dict[tuple[bytes, str], _BetaPosterior] = {}
+        # v0.6 — closed-loop calibration. Lazy-init to avoid pulling
+        # eval/ at import time of this file.
+        self._brier_tracker = None  # type: ignore[assignment]
+        # P2-16: optional bus attachment for KNOWS_DELTA broadcasting.
+        self._bus: GossipBus | None = None
+        self._bus_issuer_kid: bytes = b""
+        self._bus_namespace_id: str = ""
+
+    @property
+    def brier_tracker(self):
+        """Per-(agent, topic) Brier-score tracker.
+
+        Lazy-instantiated on first access. Lives for the kernel's
+        lifetime; mirrors to disk via ``ReputationKernel.snapshot()``
+        future work in the persistence layer (v0.6.5).
+        """
+        if self._brier_tracker is None:
+            from hypermind.eval.calibration import BrierScoreTracker
+
+            self._brier_tracker = BrierScoreTracker()
+        return self._brier_tracker
+
+    def calibration_adjustment(self, agent_id: bytes, topic: str) -> float:
+        """Return the multiplicative ``effective_n`` shrinkage for this agent.
+
+        Returns 1.0 (no-op) when there are too few oracle resolutions to
+        compute a meaningful Brier score. Otherwise ∈ [0.5, 2.0].
+        """
+        return self.brier_tracker.adjustment(agent_id, topic)
+
+    # P2-16: bus attachment --------------------------------------------------
+
+    def attach_bus(
+        self,
+        bus: GossipBus,
+        *,
+        issuer_kid: bytes,
+        namespace_id: str,
+    ) -> None:
+        """Attach a GossipBus so reputation deltas are broadcast as KNOWS_DELTA.
+
+        Call once after constructing the kernel.  ``issuer_kid`` must be the
+        32-byte Ed25519 kid of the agent/namespace that owns this kernel
+        (used to sign outbound KNOWS_DELTA messages).
+
+        Note: publication requires a signing keypair to produce verifiable
+        messages. For lightweight delta broadcast (no signature), pass an
+        unsigned message.  Full signed broadcast requires ``attach_bus_with_keypair``.
+        """
+        self._bus = bus
+        self._bus_issuer_kid = bytes(issuer_kid)
+        self._bus_namespace_id = namespace_id
+
+    def attach_bus_with_keypair(
+        self,
+        bus: GossipBus,
+        keypair: object,  # Keypair — avoid import cycle; duck-typed
+        *,
+        namespace_id: str,
+    ) -> None:
+        """Attach a GossipBus with a signing keypair for signed KNOWS_DELTA.
+
+        ``keypair`` must be a :class:`~hypermind.crypto.signing.Keypair`
+        instance.  Use this variant when you want fully verified broadcasts.
+        """
+        self._bus = bus
+        self._bus_issuer_kid = bytes(keypair.kid)  # type: ignore[union-attr]
+        self._bus_namespace_id = namespace_id
+        self._bus_keypair = keypair  # type: ignore[assignment]
+
+    def _schedule_knows_delta_broadcast(
+        self,
+        agent_id: bytes,
+        topic: str,
+        alpha_delta: float,
+        beta_delta: float,
+        evidence_kid: bytes | None = None,
+    ) -> None:
+        """Fire-and-forget KNOWS_DELTA broadcast after a reputation update.
+
+        Uses ``asyncio.create_task`` so synchronous callers (``record_outcome``,
+        ``vouch``) can trigger the async broadcast without blocking.  Silently
+        suppresses errors when no event loop is running (e.g. in synchronous
+        test contexts that don't need the broadcast).
+        """
+        if self._bus is None:
+            return
+        keypair = getattr(self, "_bus_keypair", None)
+        if keypair is None:
+            return  # unsigned broadcasts not implemented — skip
+        bus = self._bus
+        namespace_id = self._bus_namespace_id
+        hlc = int(time.time() * 1000)
+
+        async def _broadcast() -> None:
+            from hypermind.transport.knows_delta import (
+                KnowsDeltaBucket,
+                KnowsDeltaMessage,
+                publish_knows_delta,
+            )
+
+            bucket = KnowsDeltaBucket(
+                topic_id=topic,
+                subject_kid=bytes(agent_id),
+                alpha_delta=alpha_delta,
+                beta_delta=beta_delta,
+                evidence_kid=evidence_kid,
+            )
+            msg = KnowsDeltaMessage.create(
+                keypair=keypair,
+                namespace_id=namespace_id,
+                hlc=hlc,
+                buckets=[bucket],
+            )
+            try:
+                await publish_knows_delta(msg, bus)
+            except Exception:
+                pass  # best-effort
+
+        try:
+            loop = asyncio.get_running_loop()
+            _task = loop.create_task(_broadcast())  # fire-and-forget; reference kept to avoid GC
+            del _task  # suppress RUF006: intentionally not awaited
+        except RuntimeError:
+            pass  # no running event loop — skip broadcast
+
+    @staticmethod
+    def _staleness_factor(
+        evidence_hlc_ms: int,
+        now_hlc_ms: int,
+        *,
+        staleness_window_ms: int = STALENESS_WINDOW_MS_DEFAULT,
+        lambda_staleness: float = LAMBDA_STALENESS_DEFAULT,
+    ) -> float:
+        """Return a weight in (0, 1] based on how old the evidence is.
+
+        Evidence within ``staleness_window_ms`` of now has full weight 1.0.
+        Evidence older than the window decays exponentially with rate
+        ``lambda_staleness`` per day.
+        """
+        age_ms = now_hlc_ms - evidence_hlc_ms
+        if age_ms <= staleness_window_ms:
+            return 1.0
+        excess_days = (age_ms - staleness_window_ms) / 86_400_000
+        return math.exp(-lambda_staleness * excess_days)
+
+    def _get(self, agent_id: bytes, topic: str) -> _BetaPosterior:
+        key = (bytes(agent_id), topic)
+        if key not in self._posteriors:
+            self._posteriors[key] = _BetaPosterior()
+        return self._posteriors[key]
+
+    def _decay(self, p: _BetaPosterior, *, now_ms: int) -> None:
+        elapsed_days = (now_ms - p.last_update_ms) / (1000 * 60 * 60 * 24)
+        if elapsed_days <= 0:
+            return
+        decay = math.exp(-math.log(2) * elapsed_days / self.half_life_days)
+        # Decay only the "above-prior" mass; preserve the Laplace prior.
+        p.alpha = 1.0 + (p.alpha - 1.0) * decay
+        p.beta = 1.0 + (p.beta - 1.0) * decay
+        p.last_update_ms = now_ms
+
+    def record_outcome(
+        self,
+        agent_id: bytes,
+        topic: str,
+        *,
+        correct: bool,
+        weight: float = 1.0,
+        evidence_hlc_ms: int | None = None,
+    ) -> ReputationSnapshot:
+        """Update reputation given a confirmed outcome.
+
+        ``evidence_hlc_ms`` is the HLC timestamp of the original claim (the
+        evidence age). When provided, the effective weight is multiplied by
+        ``_staleness_factor`` so stale evidence has less influence than fresh
+        evidence.  When absent, the current time is used (full weight).
+        """
+        now_ms = int(time.time() * 1000)
+        if evidence_hlc_ms is not None:
+            stale_w = self._staleness_factor(
+                evidence_hlc_ms,
+                now_ms,
+                staleness_window_ms=self.staleness_window_ms,
+                lambda_staleness=self.lambda_staleness,
+            )
+            weight = weight * stale_w
+        p = self._get(agent_id, topic)
+        self._decay(p, now_ms=now_ms)
+        if correct:
+            p.alpha += weight
+        else:
+            # Smooth slashing: shave a fraction of α, increment β.
+            p.alpha = max(1.0, p.alpha * (1 - self.lam))
+            p.beta += self.mu * weight + weight  # weighted bad outcome
+        # Push to score_history HERE — once per real observation.
+        # snapshot() must remain a pure read so consult/discover_mentors
+        # don't bias momentum_z by calling it n·log(n) times in panel
+        # selection (closes self-heal Cycle-3 Finding #16).
+        score = p.alpha / (p.alpha + p.beta)
+        p.score_history.append(score)
+        # P2-16: broadcast the applied delta to peers (fire-and-forget).
+        alpha_delta = weight if correct else 0.0
+        beta_delta = 0.0 if correct else self.mu * weight + weight
+        self._schedule_knows_delta_broadcast(agent_id, topic, alpha_delta, beta_delta)
+        return self.snapshot(agent_id, topic)
+
+    def vouch(self, voucher: bytes, vouchee: bytes, topic: str, *, strength: float = 1.0) -> None:
+        """Boost vouchee's reputation by a fraction of voucher's confidence.
+
+        Cap (closes self-heal Cycle-1 Finding #4): a single vouch may
+        contribute at most 5% of the VOUCHER's own α — so a high-rep
+        agent cannot transfer their full reputation to a brand-new
+        cohort in one move (ring-laundering defence). The pre-cap line
+        `min(α, α * 1.05)` was a no-op (always returns α since 1.05>1).
+        """
+        voucher_p = self._get(voucher, topic)
+        self._decay(voucher_p, now_ms=int(time.time() * 1000))
+        boost = strength * (self.snapshot(voucher, topic).score - self.threshold)
+        if boost <= 0:
+            return
+        # Hard cap: 5% of the voucher's above-prior mass.
+        cap = 0.05 * max(0.0, voucher_p.alpha - 1.0)
+        boost = min(boost, cap) if cap > 0 else 0.0
+        if boost <= 0:
+            return
+        p = self._get(vouchee, topic)
+        self._decay(p, now_ms=int(time.time() * 1000))
+        p.alpha += boost
+
+    def snapshot(self, agent_id: bytes, topic: str) -> ReputationSnapshot:
+        now_ms = int(time.time() * 1000)
+        p = self._get(agent_id, topic)
+        # Compute decayed values on a scratch copy — do NOT mutate p so
+        # concurrent reads don't race on last_update_ms (closes #53).
+        elapsed_days = (now_ms - p.last_update_ms) / (1000 * 60 * 60 * 24)
+        if elapsed_days > 0:
+            decay = math.exp(-math.log(2) * elapsed_days / self.half_life_days)
+            alpha = 1.0 + (p.alpha - 1.0) * decay
+            beta = 1.0 + (p.beta - 1.0) * decay
+        else:
+            alpha, beta = p.alpha, p.beta
+        score = alpha / (alpha + beta)
+        # Note: score_history is appended in record_outcome (the actual
+        # observation point), NOT here. snapshot() is a pure read for
+        # panel selection / discover_mentors / consult routing — appending
+        # on every read would n·log(n)-bias momentum_z.
+        z = 0.0
+        if len(p.score_history) >= 5:
+            mean = sum(p.score_history) / len(p.score_history)
+            var = sum((s - mean) ** 2 for s in p.score_history) / len(p.score_history)
+            std = math.sqrt(var) or 1e-6
+            z = (score - mean) / std
+        return ReputationSnapshot(
+            agent_id=bytes(agent_id),
+            topic=topic,
+            score=score,
+            n_observations=int(alpha + beta - 2),
+            last_updated_ms=p.last_update_ms,
+            momentum_z=z,
+        )
+
+    def above_threshold(self, agent_id: bytes, topic: str) -> bool:
+        return self.snapshot(agent_id, topic).score >= self.threshold
+
+    def update_with_correlated_agreement(
+        self,
+        reports: list,
+        *,
+        topic: str,
+        alpha: float = 1.0,
+        threshold: float = 0.0,
+    ) -> dict[bytes, float]:
+        """Apply Bayesian-Truth-Serum / correlated-agreement scoring.
+
+        See :mod:`hypermind.knowledge.correlated_agreement` (ROADMAP §0.2.2).
+        Returns the raw score map (reporter_id → score) so callers can
+        inspect calibration without a second computation.
+        """
+        from hypermind.knowledge.correlated_agreement import (
+            update_kernel_with_reports,
+        )
+
+        return update_kernel_with_reports(
+            self, reports, topic=topic, alpha=alpha, threshold=threshold
+        )