rootmemory 0.1.0__py3-none-any.whl

rootmemory/services/promotion_service.py

@@ -0,0 +1,318 @@
+"""PromotionService: the gate between private reasoning and shared memory.
+
+A claim becomes shared knowledge only by passing this gate, and every
+evaluation - pass or fail - is written to promotion_audits. The gate counts
+*independent evidence sources*, never agreeing agents, which is what stops
+three copies of one inference from looking like corroboration.
+"""
+
+from __future__ import annotations
+
+import uuid
+from dataclasses import asdict, dataclass, field
+
+from sqlalchemy.orm import Session
+
+from rootmemory.config import Settings, get_settings
+from rootmemory.db.base import utcnow
+from rootmemory.errors import NodeNotFoundError
+from rootmemory.models.claim import Claim
+from rootmemory.models.enums import (
+    ClaimStatus,
+    EpistemicStatus,
+    LinkRole,
+    PromotionResultType,
+    Visibility,
+)
+from rootmemory.repositories.audit_repo import AuditRepository
+from rootmemory.repositories.belief_repo import BeliefRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.services.contradiction_service import ClaimContext, ContradictionService
+
+
+@dataclass(frozen=True, slots=True)
+class PromotionPolicy:
+    """The rules a claim must satisfy to enter shared memory (spec section 21)."""
+
+    min_independent_support: int = 2
+    min_confidence: float = 0.75
+    max_high_confidence_contradictions: int = 0
+    contradiction_confidence_threshold: float = 0.75
+    require_valid_provenance: bool = True
+    version: str = "v1"
+
+    @classmethod
+    def from_settings(cls, settings: Settings | None = None) -> PromotionPolicy:
+        settings = settings or get_settings()
+        return cls(
+            min_independent_support=settings.promotion_min_independent_support,
+            min_confidence=settings.promotion_min_confidence,
+            max_high_confidence_contradictions=(
+                settings.promotion_max_high_confidence_contradictions
+            ),
+            contradiction_confidence_threshold=(
+                settings.promotion_contradiction_confidence_threshold
+            ),
+            version=settings.promotion_policy_version,
+        )
+
+    def as_dict(self) -> dict[str, object]:
+        return asdict(self)
+
+
+# Reason codes. Stored in the audit log, so they are stable strings rather than
+# free text.
+REASON_SUPPORT_MET = "independent_support_requirement_met"
+REASON_SUPPORT_INSUFFICIENT = "independent_support_requirement_not_met"
+REASON_CONFIDENCE_MET = "confidence_requirement_met"
+REASON_CONFIDENCE_LOW = "confidence_below_threshold"
+REASON_NO_CONTRADICTIONS = "no_unresolved_contradictions"
+REASON_CONTRADICTED = "unresolved_contradiction_present"
+REASON_NO_PROVENANCE = "no_valid_provenance"
+REASON_SHARED_ROOT = "supporting_beliefs_share_a_single_evidence_root"
+
+
+@dataclass(slots=True)
+class PromotionEvaluation:
+    """The result of running the gate. Both counts are always present."""
+
+    claim_id: uuid.UUID
+    claim_key: str
+    supporting_belief_count: int
+    agreeing_agent_count: int
+    independent_support_count: int
+    contradiction_count: int
+    independent_contradiction_count: int
+    aggregate_confidence: float
+    naive_average_confidence: float
+    decision: PromotionResultType
+    reasons: list[str] = field(default_factory=list)
+    policy: PromotionPolicy = field(default_factory=PromotionPolicy)
+    unresolved_contradiction_ids: list[uuid.UUID] = field(default_factory=list)
+    root_observation_ids: list[uuid.UUID] = field(default_factory=list)
+
+    @property
+    def promoted(self) -> bool:
+        return self.decision == PromotionResultType.PROMOTED
+
+    @property
+    def explanation(self) -> str:
+        """One sentence a human (or an agent) can act on."""
+        if self.promoted:
+            return (
+                f"{self.supporting_belief_count} supporting beliefs rest on "
+                f"{self.independent_support_count} independent evidence sources."
+            )
+        if REASON_SHARED_ROOT in self.reasons:
+            return (
+                f"{self.supporting_belief_count} supporting beliefs descend from a single "
+                f"evidence source."
+            )
+        if REASON_CONTRADICTED in self.reasons:
+            return (
+                f"{len(self.unresolved_contradiction_ids)} unresolved high-confidence "
+                f"contradiction(s) stand against this claim."
+            )
+        if REASON_SUPPORT_INSUFFICIENT in self.reasons:
+            return (
+                f"{self.independent_support_count} independent evidence source(s), "
+                f"{self.policy.min_independent_support} required."
+            )
+        if REASON_CONFIDENCE_LOW in self.reasons:
+            return (
+                f"aggregate confidence {self.aggregate_confidence} is below "
+                f"{self.policy.min_confidence}."
+            )
+        return "claim does not satisfy the promotion policy."
+
+    def as_dict(self) -> dict[str, object]:
+        return {
+            "claim_id": str(self.claim_id),
+            "claim_key": self.claim_key,
+            "supporting_belief_count": self.supporting_belief_count,
+            "agreeing_agents": self.agreeing_agent_count,
+            "independent_support_count": self.independent_support_count,
+            "contradiction_count": self.contradiction_count,
+            "independent_contradiction_count": self.independent_contradiction_count,
+            "aggregate_confidence": self.aggregate_confidence,
+            "naive_average_confidence": self.naive_average_confidence,
+            "decision": "promote" if self.promoted else "reject",
+            "reasons": list(self.reasons),
+            "explanation": self.explanation,
+            "policy_version": self.policy.version,
+        }
+
+
+class PromotionService:
+    """The only component allowed to confirm a claim or share a belief."""
+
+    def __init__(self, session: Session, policy: PromotionPolicy | None = None) -> None:
+        self.session = session
+        self.policy = policy or PromotionPolicy.from_settings()
+        self.claims = ClaimRepository(session)
+        self.beliefs = BeliefRepository(session)
+        self.audits = AuditRepository(session)
+        self.contradictions = ContradictionService(session)
+
+    # ------------------------------------------------------------------
+    # evaluation
+    # ------------------------------------------------------------------
+
+    def evaluate(self, claim_id: uuid.UUID, persist_audit: bool = True) -> PromotionEvaluation:
+        """Run the promotion policy against a claim without changing its status."""
+        context = self.contradictions.build_context(claim_id)
+        evaluation = self._evaluate_context(context)
+        self.contradictions.sync_claim_metrics(context)
+        if persist_audit:
+            self._write_audit(evaluation)
+        return evaluation
+
+    def _evaluate_context(self, context: ClaimContext) -> PromotionEvaluation:
+        support = context.support
+        contradiction = context.contradiction
+
+        unresolved = self.contradictions.unresolved_contradictions(
+            context, self.policy.contradiction_confidence_threshold
+        )
+
+        reasons: list[str] = []
+
+        has_provenance = support.independent_source_count > 0
+        if self.policy.require_valid_provenance and not has_provenance:
+            reasons.append(REASON_NO_PROVENANCE)
+
+        support_ok = support.independent_source_count >= self.policy.min_independent_support
+        if support_ok:
+            reasons.append(REASON_SUPPORT_MET)
+        else:
+            reasons.append(REASON_SUPPORT_INSUFFICIENT)
+            # The interesting sub-case: plenty of agreement, one source.
+            if support.shares_single_source:
+                reasons.append(REASON_SHARED_ROOT)
+
+        confidence_ok = support.aggregate_confidence >= self.policy.min_confidence
+        reasons.append(REASON_CONFIDENCE_MET if confidence_ok else REASON_CONFIDENCE_LOW)
+
+        contradictions_ok = len(unresolved) <= self.policy.max_high_confidence_contradictions
+        reasons.append(REASON_NO_CONTRADICTIONS if contradictions_ok else REASON_CONTRADICTED)
+
+        passes = (
+            support_ok
+            and confidence_ok
+            and contradictions_ok
+            and (has_provenance or not self.policy.require_valid_provenance)
+        )
+
+        return PromotionEvaluation(
+            claim_id=context.claim.id,
+            claim_key=context.claim.claim_key,
+            supporting_belief_count=support.belief_count,
+            agreeing_agent_count=support.agreeing_agent_count,
+            independent_support_count=support.independent_source_count,
+            contradiction_count=contradiction.belief_count,
+            independent_contradiction_count=contradiction.independent_source_count,
+            aggregate_confidence=support.aggregate_confidence,
+            naive_average_confidence=support.naive_confidence,
+            decision=(
+                PromotionResultType.PROMOTED if passes else PromotionResultType.REJECTED
+            ),
+            reasons=reasons,
+            policy=self.policy,
+            unresolved_contradiction_ids=unresolved,
+            root_observation_ids=support.root_observation_ids,
+        )
+
+    # ------------------------------------------------------------------
+    # promotion
+    # ------------------------------------------------------------------
+
+    def promote(self, claim_id: uuid.UUID) -> PromotionEvaluation:
+        """Attempt to move a claim into shared memory.
+
+        The gate is always re-run here: a caller's earlier evaluation is never
+        trusted (spec section 27.8).
+
+        The claim row is locked first, so concurrent workers serialize on it
+        rather than racing between reading the evidence and writing the verdict.
+        """
+        if self.claims.get_for_update(claim_id) is None:
+            raise NodeNotFoundError(f"claim {claim_id} does not exist")
+        context = self.contradictions.build_context(claim_id)
+        evaluation = self._evaluate_context(context)
+        self.contradictions.sync_claim_metrics(context)
+        self._apply(context, evaluation)
+        self._write_audit(evaluation)
+        return evaluation
+
+    def recompute(self, claim_id: uuid.UUID) -> PromotionEvaluation:
+        """Re-run the gate on a claim whose evidence changed.
+
+        Used by cascade repair: a confirmed claim that no longer passes is
+        downgraded rather than left standing on retracted evidence.
+        """
+        return self.promote(claim_id)
+
+    def _apply(self, context: ClaimContext, evaluation: PromotionEvaluation) -> None:
+        claim = context.claim
+        supporting = self.claims.beliefs_for_claim(claim.id, LinkRole.SUPPORTS)
+
+        if evaluation.promoted:
+            claim.status = str(ClaimStatus.CONFIRMED)
+            if claim.promoted_at is None:
+                claim.promoted_at = utcnow()
+            for belief in supporting:
+                if belief.epistemic_status != EpistemicStatus.RETRACTED:
+                    belief.visibility = str(Visibility.SHARED)
+                    belief.epistemic_status = str(EpistemicStatus.CONFIRMED)
+        else:
+            claim.status = str(self._rejected_status(context, evaluation))
+            claim.promoted_at = None
+            for belief in supporting:
+                # A failed candidate falls back to private; the reason lives in
+                # the audit log.
+                if belief.visibility != Visibility.PRIVATE:
+                    belief.visibility = str(Visibility.PRIVATE)
+                if belief.epistemic_status == EpistemicStatus.CONFIRMED:
+                    belief.epistemic_status = str(EpistemicStatus.BELIEVED)
+
+        self.session.flush()
+
+    def _rejected_status(
+        self, context: ClaimContext, evaluation: PromotionEvaluation
+    ) -> ClaimStatus:
+        if evaluation.unresolved_contradiction_ids:
+            return ClaimStatus.CONTRADICTED
+        # Linked beliefs including retracted ones: "nobody ever asserted this"
+        # and "everyone who asserted it has withdrawn" are different states.
+        linked = self.claims.beliefs_for_claim(context.claim.id, LinkRole.SUPPORTS)
+        if not linked:
+            return ClaimStatus.UNCONFIRMED
+        if evaluation.independent_support_count == 0:
+            # Support exists on paper but rests on no valid evidence any more.
+            return ClaimStatus.RETRACTED
+        return ClaimStatus.PROVISIONAL
+
+    # ------------------------------------------------------------------
+    # audit
+    # ------------------------------------------------------------------
+
+    def _write_audit(self, evaluation: PromotionEvaluation) -> None:
+        self.audits.record_promotion(
+            claim_id=evaluation.claim_id,
+            supporting_belief_count=evaluation.supporting_belief_count,
+            agreeing_agent_count=evaluation.agreeing_agent_count,
+            independent_support_count=evaluation.independent_support_count,
+            contradiction_count=evaluation.contradiction_count,
+            independent_contradiction_count=evaluation.independent_contradiction_count,
+            aggregate_confidence=evaluation.aggregate_confidence,
+            result=str(evaluation.decision),
+            reasons=list(evaluation.reasons),
+            policy_version=self.policy.version,
+            policy_snapshot=self.policy.as_dict(),
+        )
+
+    def require_claim(self, claim_id: uuid.UUID) -> Claim:
+        claim = self.claims.get(claim_id)
+        if claim is None:
+            raise NodeNotFoundError(f"claim {claim_id} does not exist")
+        return claim

rootmemory/services/provenance_service.py

@@ -0,0 +1,282 @@
+"""ProvenanceService: traversal over the causal dependency graph.
+
+This module is the foundation of the whole system. Everything else -
+independence counting, the promotion gate, cascade repair - is expressed in
+terms of the four operations here:
+
+    parents()              one hop towards the evidence
+    find_evidence_roots()  the observations a node ultimately rests on
+    path_exists()          cycle prevention
+    cascade_descendants()  everything affected by a retraction
+
+All of it is deterministic. No LLM is involved (spec section 47).
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+
+from sqlalchemy.orm import Session
+
+from rootmemory.models.belief import Belief
+from rootmemory.models.enums import CAUSAL_EDGE_TYPES, LinkRole, NodeType, ValidityStatus
+from rootmemory.models.node_ref import NodeRef
+from rootmemory.models.observation import Observation
+from rootmemory.repositories.belief_repo import BeliefRepository
+from rootmemory.repositories.claim_repo import ClaimRepository
+from rootmemory.repositories.decision_repo import DecisionRepository
+from rootmemory.repositories.edge_repo import EdgeRepository
+from rootmemory.repositories.observation_repo import ObservationRepository
+
+#: Observation validity states that may act as evidence roots by default.
+DEFAULT_ROOT_STATUSES: frozenset[str] = frozenset({str(ValidityStatus.VALID)})
+
+#: Safety valve for path enumeration on dense graphs.
+MAX_ENUMERATED_PATHS = 200
+
+
+@dataclass(slots=True)
+class EvidenceRoots:
+    """The result of walking a node back to its evidence.
+
+    ``roots`` holds the observations that currently qualify as evidence.
+    ``excluded_roots`` holds ancestors that were reached but rejected (invalid
+    or disputed), which is what makes a retraction explainable rather than a
+    silent disappearance.
+    """
+
+    roots: set[uuid.UUID] = field(default_factory=set)
+    excluded_roots: dict[uuid.UUID, str] = field(default_factory=dict)
+    visited_nodes: int = 0
+
+    def __len__(self) -> int:
+        return len(self.roots)
+
+
+@dataclass(slots=True)
+class CascadeResult:
+    """Everything downstream of a node, split by node type."""
+
+    beliefs: list[uuid.UUID] = field(default_factory=list)
+    claims: list[uuid.UUID] = field(default_factory=list)
+    decisions: list[uuid.UUID] = field(default_factory=list)
+
+
+class ProvenanceService:
+    """Graph traversal. Holds no state beyond the session it was given."""
+
+    def __init__(self, session: Session) -> None:
+        self.session = session
+        self.edges = EdgeRepository(session)
+        self.observations = ObservationRepository(session)
+        self.beliefs = BeliefRepository(session)
+        self.claims = ClaimRepository(session)
+        self.decisions = DecisionRepository(session)
+
+    # ------------------------------------------------------------------
+    # single hop
+    # ------------------------------------------------------------------
+
+    def parents(self, node: NodeRef) -> list[NodeRef]:
+        """Nodes that ``node`` was derived from or depends on."""
+        edges = self.edges.outgoing([node.id], CAUSAL_EDGE_TYPES)
+        return [NodeRef(e.to_node_id, NodeType(e.to_node_type)) for e in edges]
+
+    def children(self, node: NodeRef) -> list[NodeRef]:
+        """Nodes that were derived from ``node`` (causal edges only)."""
+        edges = self.edges.incoming([node.id], CAUSAL_EDGE_TYPES)
+        return [NodeRef(e.from_node_id, NodeType(e.from_node_type)) for e in edges]
+
+    # ------------------------------------------------------------------
+    # evidence roots (spec section 18)
+    # ------------------------------------------------------------------
+
+    def find_evidence_roots(
+        self,
+        node: NodeRef,
+        allowed_statuses: Iterable[str] = DEFAULT_ROOT_STATUSES,
+    ) -> EvidenceRoots:
+        """Walk ``node`` back to the observations it ultimately rests on.
+
+        Cycle-safe: every node is expanded at most once, so a corrupted graph
+        can slow this down but can never hang it.
+
+        Observations whose validity is not in ``allowed_statuses`` are recorded
+        in ``excluded_roots`` and do not count as evidence.
+        """
+        allowed = {str(s) for s in allowed_statuses}
+        result = EvidenceRoots()
+        visited: set[uuid.UUID] = set()
+        frontier: list[NodeRef] = [node]
+
+        while frontier:
+            # Nodes not seen before, deduplicated within this level.
+            level: dict[uuid.UUID, NodeRef] = {}
+            for ref in frontier:
+                if ref.id not in visited:
+                    visited.add(ref.id)
+                    level[ref.id] = ref
+            if not level:
+                break
+            result.visited_nodes += len(level)
+
+            observation_ids = [r.id for r in level.values() if r.type == NodeType.OBSERVATION]
+            for observation in self.observations.get_many(observation_ids):
+                if observation.validity_status in allowed:
+                    result.roots.add(observation.id)
+                else:
+                    result.excluded_roots[observation.id] = observation.validity_status
+
+            # Observations are terminal; only non-observations are expanded.
+            expandable = [r.id for r in level.values() if r.type != NodeType.OBSERVATION]
+            next_frontier: list[NodeRef] = []
+            for edge in self.edges.outgoing(expandable, CAUSAL_EDGE_TYPES):
+                next_frontier.append(NodeRef(edge.to_node_id, NodeType(edge.to_node_type)))
+            frontier = next_frontier
+
+        return result
+
+    def find_evidence_root_observations(
+        self,
+        node: NodeRef,
+        allowed_statuses: Iterable[str] = DEFAULT_ROOT_STATUSES,
+    ) -> list[Observation]:
+        """``find_evidence_roots`` but returning the observation rows."""
+        roots = self.find_evidence_roots(node, allowed_statuses)
+        return list(self.observations.get_many(roots.roots))
+
+    def evidence_roots_for_beliefs(
+        self,
+        belief_ids: Iterable[uuid.UUID],
+        allowed_statuses: Iterable[str] = DEFAULT_ROOT_STATUSES,
+    ) -> dict[uuid.UUID, set[uuid.UUID]]:
+        """Evidence roots for many beliefs at once, keyed by belief id."""
+        return {
+            belief_id: self.find_evidence_roots(NodeRef.belief(belief_id), allowed_statuses).roots
+            for belief_id in belief_ids
+        }
+
+    # ------------------------------------------------------------------
+    # paths and cycles (spec section 28)
+    # ------------------------------------------------------------------
+
+    def path_exists(self, source: NodeRef, target: NodeRef) -> bool:
+        """True when ``target`` is a causal ancestor of ``source``."""
+        if source.id == target.id:
+            return True
+        visited: set[uuid.UUID] = {source.id}
+        frontier = [source.id]
+        while frontier:
+            next_frontier: list[uuid.UUID] = []
+            for edge in self.edges.outgoing(frontier, CAUSAL_EDGE_TYPES):
+                if edge.to_node_id == target.id:
+                    return True
+                if edge.to_node_id not in visited:
+                    visited.add(edge.to_node_id)
+                    next_frontier.append(edge.to_node_id)
+            frontier = next_frontier
+        return False
+
+    def would_create_cycle(self, source: NodeRef, target: NodeRef) -> bool:
+        """True when adding ``source -> target`` would close a loop.
+
+        A new edge points from a node to something it depends on, so the graph
+        stays acyclic exactly when ``source`` is not already an ancestor of
+        ``target``.
+        """
+        return self.path_exists(target, source)
+
+    def enumerate_paths(
+        self,
+        node: NodeRef,
+        max_paths: int = MAX_ENUMERATED_PATHS,
+    ) -> list[list[str]]:
+        """Every causal path from ``node`` down to a terminal ancestor.
+
+        Paths are returned as lists of "type:id" strings, nearest node first.
+        Cyclic branches are cut rather than followed.
+        """
+        paths: list[list[str]] = []
+        stack: list[tuple[NodeRef, list[NodeRef]]] = [(node, [node])]
+
+        while stack and len(paths) < max_paths:
+            current, trail = stack.pop()
+            parents = [] if current.type == NodeType.OBSERVATION else self.parents(current)
+            seen_ids = {n.id for n in trail}
+            unseen = [p for p in parents if p.id not in seen_ids]
+            if not unseen:
+                paths.append([str(n) for n in trail])
+                continue
+            for parent in unseen:
+                stack.append((parent, [*trail, parent]))
+
+        return paths
+
+    # ------------------------------------------------------------------
+    # descendants (spec section 25)
+    # ------------------------------------------------------------------
+
+    def cascade_descendants(self, node: NodeRef) -> CascadeResult:
+        """Everything downstream of ``node``.
+
+        The walk crosses node types explicitly:
+
+            observation/belief -> beliefs derived from it   (causal edges)
+            belief             -> claims it supports or contradicts
+            claim              -> decisions that depend on it
+
+        Beliefs are collected transitively first, so a claim several derivation
+        hops away is still found.
+        """
+        result = CascadeResult()
+
+        # 1. transitive belief descendants
+        visited: set[uuid.UUID] = {node.id}
+        frontier: list[uuid.UUID] = [node.id]
+        belief_ids: list[uuid.UUID] = []
+        while frontier:
+            next_frontier: list[uuid.UUID] = []
+            for edge in self.edges.incoming(frontier, CAUSAL_EDGE_TYPES):
+                if edge.from_node_id in visited:
+                    continue
+                visited.add(edge.from_node_id)
+                if edge.from_node_type == NodeType.BELIEF:
+                    belief_ids.append(edge.from_node_id)
+                    next_frontier.append(edge.from_node_id)
+                elif edge.from_node_type == NodeType.DECISION:
+                    result.decisions.append(edge.from_node_id)
+            frontier = next_frontier
+        result.beliefs = belief_ids
+
+        # 2. claims those beliefs are attached to
+        result.claims = [claim.id for claim in self.claims.claims_for_beliefs(belief_ids)]
+
+        # 3. decisions depending on those claims
+        for decision in self.decisions.decisions_for_claims(result.claims):
+            if decision.id not in result.decisions:
+                result.decisions.append(decision.id)
+
+        return result
+
+    # ------------------------------------------------------------------
+    # helpers
+    # ------------------------------------------------------------------
+
+    def node_exists(self, node: NodeRef) -> bool:
+        """Whether the referenced row is present in its table."""
+        match node.type:
+            case NodeType.OBSERVATION:
+                return self.observations.get(node.id) is not None
+            case NodeType.BELIEF:
+                return self.beliefs.get(node.id) is not None
+            case NodeType.CLAIM:
+                return self.claims.get(node.id) is not None
+            case NodeType.DECISION:
+                return self.decisions.get(node.id) is not None
+        return False
+
+    def beliefs_in_role(self, claim_id: uuid.UUID, role: LinkRole) -> Sequence[Belief]:
+        """Beliefs linked to a claim in the given role."""
+        return self.claims.beliefs_for_claim(claim_id, role)

rootmemory/services/scoring_service.py

@@ -0,0 +1,53 @@
+"""Root-aware confidence aggregation (spec section 22).
+
+Averaging the confidence of every supporting belief is wrong here: three
+copies of one inference would inflate the average exactly the way three copies
+inflate a naive support count. So confidence is aggregated *per independent
+evidence root* instead.
+
+These are pure functions over plain data, which keeps them trivially testable
+and free of any database dependency.
+"""
+
+from __future__ import annotations
+
+import uuid
+from collections.abc import Mapping, Sequence
+
+
+def aggregate_confidence_by_root(
+    beliefs_by_source: Mapping[str, Sequence[uuid.UUID]],
+    confidence_by_belief: Mapping[uuid.UUID, float],
+) -> float:
+    """Aggregate confidence across independent sources.
+
+    For each independent source, the strongest belief resting on it is taken;
+    those per-source values are then averaged. A source can therefore never
+    contribute more than once, no matter how many times its conclusion was
+    copied.
+
+    Returns 0.0 when there is no supporting evidence at all.
+    """
+    if not beliefs_by_source:
+        return 0.0
+
+    per_source: list[float] = []
+    for belief_ids in beliefs_by_source.values():
+        confidences = [confidence_by_belief[b] for b in belief_ids if b in confidence_by_belief]
+        if confidences:
+            per_source.append(max(confidences))
+
+    if not per_source:
+        return 0.0
+    return round(sum(per_source) / len(per_source), 6)
+
+
+def naive_average_confidence(confidences: Sequence[float]) -> float:
+    """Flat mean over every belief.
+
+    Kept for the baseline comparison in experiments/ so the two aggregation
+    strategies can be reported side by side.
+    """
+    if not confidences:
+        return 0.0
+    return round(sum(confidences) / len(confidences), 6)