eduevidence 5.2.0 → 6.2.0

package/engine/autoresearch/commit.py

@@ -0,0 +1,132 @@
+"""Atomic, append-only Graph commit for Evidence Autoresearch staging bundles.
+
+One ResearchIteration may add several graph entity types, but it must create at
+most one GraphRevision. Identical already-present entities are no-ops; the same
+entity id with different scientific content is an append-only conflict rather
+than an overwrite. The caller must supply the graph revision against which the
+research request was created so stale results fail closed.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from engine.graph_store import GRAPH_TABLES, GraphMutation, GraphStore
+
+_ID_KEYS = {
+    "sources": "source_id",
+    "studies": "study_id",
+    "findings": "finding_id",
+    "outcomes": "outcome_id",
+    "claims": "claim_id",
+    "evidence_links": "evidence_link_id",
+    "audits": "audit_id",
+}
+_VALID_SOURCE_STATUSES = {"valid", "accepted_partial"}
+
+
+def _rows(payload: dict[str, Any], table: str) -> list[dict]:
+    value = payload.get(table, [])
+    if value is None:
+        return []
+    if not isinstance(value, list) or any(not isinstance(row, dict) for row in value):
+        raise ValueError(f"staging bundle field {table!r} must be a list of objects")
+    return value
+
+
+def build_append_only_mutation(
+    store: GraphStore,
+    payload: dict[str, Any],
+) -> tuple[GraphMutation, dict[str, list[str]]]:
+    """Return only genuinely new entities plus their ids.
+
+    GraphStore performs schema and cross-entity validation on the final merged
+    snapshot. This function adds the Autoresearch-specific append-only and
+    validated-source gates before that atomic commit.
+    """
+    upserts: dict[str, list[dict]] = {}
+    added: dict[str, list[str]] = {}
+
+    existing_tables = {table: store.read_table(table) for table in GRAPH_TABLES}
+    for table in GRAPH_TABLES:
+        id_key = _ID_KEYS[table]
+        existing = {row[id_key]: row for row in existing_tables[table]}
+        seen_incoming: dict[str, dict] = {}
+        fresh: list[dict] = []
+        fresh_ids: list[str] = []
+        for row in _rows(payload, table):
+            entity_id = row.get(id_key)
+            if not isinstance(entity_id, str) or not entity_id:
+                raise ValueError(f"{table} staging entity missing {id_key}")
+            prior_incoming = seen_incoming.get(entity_id)
+            if prior_incoming is not None:
+                if prior_incoming != row:
+                    raise ValueError(
+                        f"append-only conflict: duplicate incoming {table} id {entity_id} has different content"
+                    )
+                continue
+            seen_incoming[entity_id] = row
+            prior = existing.get(entity_id)
+            if prior is not None:
+                if prior != row:
+                    raise ValueError(
+                        f"append-only conflict: {table} {entity_id} already exists with different content"
+                    )
+                continue
+            if table == "sources" and row.get("validation_status") not in _VALID_SOURCE_STATUSES:
+                raise ValueError(
+                    f"source {entity_id} has validation_status={row.get('validation_status')!r}; "
+                    "only valid/accepted_partial sources may enter Evidence Autoresearch"
+                )
+            fresh.append(row)
+            fresh_ids.append(entity_id)
+        if fresh:
+            upserts[table] = fresh
+            added[table] = fresh_ids
+
+    # A newly added Study may only cite a validated existing/new Source. This
+    # preserves the Fetch -> Validate -> Extract gate in the atomic path.
+    source_status = {
+        row["source_id"]: row.get("validation_status")
+        for row in existing_tables["sources"]
+    }
+    for row in upserts.get("sources", []):
+        source_status[row["source_id"]] = row.get("validation_status")
+    for study in upserts.get("studies", []):
+        for source_id in study.get("source_ids", []):
+            status = source_status.get(source_id)
+            if status not in _VALID_SOURCE_STATUSES:
+                raise ValueError(
+                    f"study {study['study_id']} references source {source_id} "
+                    f"without validated provenance (status={status!r})"
+                )
+
+    return GraphMutation(upserts=upserts, retire_ids={}), added
+
+
+def commit_staging_bundle(
+    store: GraphStore,
+    *,
+    run_id: str,
+    expected_base_revision: int,
+    payload: dict[str, Any],
+) -> int | None:
+    """Atomically append one staging bundle, or return None for a true no-op."""
+    active = store.active_revision()
+    if active != expected_base_revision:
+        raise RuntimeError(
+            f"STALE_RESEARCH_STATE: request was based on graph revision "
+            f"{expected_base_revision}, active revision is {active}; re-plan before commit"
+        )
+    mutation, added = build_append_only_mutation(store, payload)
+    if not added:
+        return None
+    # Single Writer is an architectural invariant. Recheck immediately before
+    # commit so an intervening canonical transition is detected before write.
+    if store.active_revision() != expected_base_revision:
+        raise RuntimeError("STALE_RESEARCH_STATE: graph changed while validating staging bundle")
+    revision = store.commit(
+        run_id=run_id,
+        reason="autoresearch atomic validated evidence append",
+        mutation=mutation,
+    )
+    return revision.revision

package/engine/autoresearch/contracts.py

@@ -0,0 +1,126 @@
+from __future__ import annotations
+from dataclasses import dataclass, field, asdict
+from datetime import datetime, timezone
+from enum import Enum
+from typing import Any
+
+
+def utcnow() -> str:
+    return datetime.now(timezone.utc).isoformat()
+
+
+class ResearchExperimentType(str, Enum):
+    TARGETED_RETRIEVAL = "TARGETED_RETRIEVAL"
+    COUNTER_EVIDENCE_RETRIEVAL = "COUNTER_EVIDENCE_RETRIEVAL"
+    APPLICABILITY_RETRIEVAL = "APPLICABILITY_RETRIEVAL"
+    TEMPORAL_REFRESH = "TEMPORAL_REFRESH"
+    CITATION_CHAINING = "CITATION_CHAINING"
+    SCREENING_PRIORITY = "SCREENING_PRIORITY"
+    SOURCE_RECOVERY = "SOURCE_RECOVERY"
+
+
+class IterationStatus(str, Enum):
+    COMPLETED_GAIN = "completed_gain"
+    COMPLETED_NO_GAIN = "completed_no_gain"
+    SEARCH_SATURATED = "search_saturated"
+    EMPIRICAL_NEEDED = "empirical_needed"
+    BUDGET_EXHAUSTED = "budget_exhausted"
+    TOOL_FAILURE = "tool_failure"
+    INVALID = "invalid"
+
+
+@dataclass(frozen=True)
+class ResearchBudget:
+    max_queries: int = 6
+    max_candidates: int = 30
+    max_fulltext_fetches: int = 12
+
+    def validate(self) -> None:
+        if min(self.max_queries, self.max_candidates, self.max_fulltext_fetches) < 0:
+            raise ValueError("research budget values must be non-negative")
+
+
+@dataclass(frozen=True)
+class ResearchStrategy:
+    strategy_id: str
+    experiment_type: ResearchExperimentType
+    hypothesis: str
+    expected_gain: str
+    budget: ResearchBudget = field(default_factory=ResearchBudget)
+
+    def validate(self) -> None:
+        if not self.strategy_id.strip() or not self.hypothesis.strip() or not self.expected_gain.strip():
+            raise ValueError("strategy_id, hypothesis and expected_gain are required")
+        self.budget.validate()
+
+
+@dataclass(frozen=True)
+class NegativeSearchRecord:
+    negative_search_id: str
+    research_iteration_id: str
+    gap_id: str
+    queries: tuple[str, ...]
+    providers: tuple[str, ...]
+    candidate_count: int
+    fetched_count: int
+    eligible_count: int
+    exclusion_reasons: dict[str, int] = field(default_factory=dict)
+    scope: dict[str, Any] = field(default_factory=dict)
+    searched_at: str = field(default_factory=utcnow)
+    conclusion: str = "no_eligible_evidence_found_within_search_scope"
+
+    def validate(self) -> None:
+        if self.eligible_count != 0:
+            raise ValueError("NegativeSearchRecord requires eligible_count == 0")
+        if min(self.candidate_count, self.fetched_count, self.eligible_count) < 0:
+            raise ValueError("counts must be non-negative")
+        if self.fetched_count > self.candidate_count:
+            raise ValueError("fetched_count cannot exceed candidate_count")
+        if self.conclusion != "no_eligible_evidence_found_within_search_scope":
+            raise ValueError("negative search conclusion must remain scope-bounded")
+
+
+@dataclass
+class ResearchIteration:
+    iteration_id: str
+    project_id: str
+    base_graph_revision: int
+    gap_id: str
+    strategy: ResearchStrategy
+    gap_lineage_key: str | None = None
+    execution_plan_id: str | None = None
+    search_attempts: list[dict[str, Any]] = field(default_factory=list)
+    candidate_sources: list[str] = field(default_factory=list)
+    validated_evidence_ids: list[str] = field(default_factory=list)
+    negative_search_ids: list[str] = field(default_factory=list)
+    evidence_gain: dict[str, Any] = field(default_factory=dict)
+    new_graph_revision: int | None = None
+    decision_snapshot_id: str | None = None
+    status: IterationStatus | None = None
+    started_at: str = field(default_factory=utcnow)
+    completed_at: str | None = None
+
+    def validate(self) -> None:
+        self.strategy.validate()
+        if self.base_graph_revision < 0:
+            raise ValueError("base_graph_revision must be >= 0")
+        if self.gap_lineage_key is not None and not self.gap_lineage_key.startswith("KGK-"):
+            raise ValueError("gap_lineage_key must use the KGK- prefix")
+        if self.new_graph_revision is not None:
+            if not self.validated_evidence_ids:
+                raise ValueError("no-gain iteration must not create a GraphRevision")
+            if self.new_graph_revision <= self.base_graph_revision:
+                raise ValueError("new_graph_revision must advance base revision")
+        if self.status == IterationStatus.COMPLETED_NO_GAIN and self.new_graph_revision is not None:
+            raise ValueError("completed_no_gain cannot create GraphRevision")
+
+    def complete(self, status: IterationStatus) -> None:
+        self.status = status
+        self.completed_at = utcnow()
+        self.validate()
+
+    def as_dict(self) -> dict[str, Any]:
+        out = asdict(self)
+        out["strategy"]["experiment_type"] = self.strategy.experiment_type.value
+        out["status"] = self.status.value if self.status else None
+        return out

package/engine/autoresearch/controller.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from typing import Any, Callable
+from .contracts import (
+    IterationStatus,
+    ResearchBudget,
+    ResearchExperimentType,
+    ResearchIteration,
+    ResearchStrategy,
+)
+from .gap_priority import GapPriority, rank_gaps
+from .saturation import detect_saturation, transition_to_empirical
+
+
+@dataclass(frozen=True)
+class StepResult:
+    iteration: ResearchIteration
+    priority: GapPriority
+    next_action: str
+    rationale: tuple[str, ...]
+
+
+def gap_lineage_key(gap: dict[str, Any]) -> str | None:
+    extensions = gap.get("extensions")
+    if not isinstance(extensions, dict):
+        return None
+    value = extensions.get("autoresearch_key")
+    if value is None:
+        return None
+    value = str(value).strip()
+    return value or None
+
+
+def history_matches_gap(row: dict[str, Any], gap: dict[str, Any]) -> bool:
+    """Match research history across graph revisions without conflating gaps.
+
+    New iterations persist the stable KGK lineage key. Legacy rows that predate
+    the key remain readable and match only by revision-local gap_id.
+    """
+    lineage = gap_lineage_key(gap)
+    row_lineage = row.get("gap_lineage_key")
+    if lineage and row_lineage:
+        return str(row_lineage) == lineage
+    return str(row.get("gap_id", "")) == str(gap.get("gap_id", ""))
+
+
+class EvidenceAutoresearchController:
+    """Bounded gap-to-evidence loop with strategy memory."""
+
+    def __init__(self, *, max_iterations: int = 5):
+        if not 1 <= max_iterations <= 50:
+            raise ValueError("max_iterations must be 1..50")
+        self.max_iterations = max_iterations
+
+    def select_gap(self, gaps: list[dict[str, Any]], decision: dict[str, Any] | None = None) -> GapPriority:
+        ranked = rank_gaps(
+            [
+                g for g in gaps
+                if str(g.get("status", "open")).lower()
+                not in {"resolved", "low_decision_value", "search_saturated", "empirical_needed"}
+            ],
+            decision=decision,
+        )
+        if not ranked:
+            raise ValueError("no unresolved KnowledgeGap available")
+        return ranked[0]
+
+    @staticmethod
+    def strategy_types_for(gap: dict[str, Any]) -> tuple[ResearchExperimentType, ...]:
+        gap_type = str(gap.get("gap_type", ""))
+        if gap_type == "unresolved_conflict":
+            return (
+                ResearchExperimentType.COUNTER_EVIDENCE_RETRIEVAL,
+                ResearchExperimentType.CITATION_CHAINING,
+                ResearchExperimentType.TARGETED_RETRIEVAL,
+                ResearchExperimentType.TEMPORAL_REFRESH,
+            )
+        if gap_type in {"population_gap", "context_gap"}:
+            return (
+                ResearchExperimentType.APPLICABILITY_RETRIEVAL,
+                ResearchExperimentType.TARGETED_RETRIEVAL,
+                ResearchExperimentType.CITATION_CHAINING,
+                ResearchExperimentType.TEMPORAL_REFRESH,
+            )
+        return (
+            ResearchExperimentType.TARGETED_RETRIEVAL,
+            ResearchExperimentType.CITATION_CHAINING,
+            ResearchExperimentType.TEMPORAL_REFRESH,
+            ResearchExperimentType.SOURCE_RECOVERY,
+        )
+
+    def build_strategy(
+        self,
+        priority: GapPriority,
+        gap: dict[str, Any],
+        history: list[dict[str, Any]] | None = None,
+    ) -> ResearchStrategy:
+        history = history or []
+        attempted = {
+            str((row.get("strategy") or {}).get("experiment_type", ""))
+            for row in history
+            if history_matches_gap(row, gap)
+        }
+        choices = self.strategy_types_for(gap)
+        experiment_type = next(
+            (choice for choice in choices if choice.value not in attempted),
+            choices[-1],
+        )
+        gap_type = str(gap.get("gap_type", ""))
+        lineage = gap_lineage_key(gap)
+        hypothesis = (
+            f"{experiment_type.value} for {gap_type or 'gap'} will find "
+            f"decision-relevant evidence that materially improves directness "
+            f"or resolves {priority.gap_id}."
+        )
+        strategy_anchor = lineage or priority.gap_id
+        return ResearchStrategy(
+            f"STRAT-{strategy_anchor}-{experiment_type.value.lower()}",
+            experiment_type,
+            hypothesis,
+            "decision_relevant_evidence",
+            ResearchBudget(),
+        )
+
+    def step(
+        self,
+        *,
+        project_id: str,
+        base_graph_revision: int,
+        gaps: list[dict[str, Any]],
+        decision: dict[str, Any] | None,
+        history: list[dict[str, Any]],
+        executor: Callable[[ResearchStrategy, dict[str, Any]], dict[str, Any]],
+        graph_commit: Callable[[list[str]], int | None] | None = None,
+        decision_snapshot_id: str | None = None,
+        ethics_feasible: bool = False,
+    ) -> StepResult:
+        priority = self.select_gap(gaps, decision)
+        gap = next(g for g in gaps if str(g.get("gap_id")) == priority.gap_id)
+        strategy = self.build_strategy(priority, gap, history)
+        iteration = ResearchIteration(
+            f"RIT-{len(history) + 1:04d}",
+            project_id,
+            base_graph_revision,
+            priority.gap_id,
+            strategy,
+            gap_lineage_key=gap_lineage_key(gap),
+        )
+        outcome = executor(strategy, gap)
+        if not isinstance(outcome, dict):
+            raise ValueError("research executor must return a staging JSON object")
+        if "resolved_gap_ids" in outcome:
+            raise ValueError(
+                "executor must not author KnowledgeGap RESOLVED state; append validated "
+                "evidence, re-derive gaps, and let the main adjudication engine resolve them"
+            )
+        valid = list(dict.fromkeys(outcome.get("validated_evidence_ids") or []))
+        iteration.validated_evidence_ids = valid
+        iteration.candidate_sources = list(outcome.get("candidate_sources") or [])
+        iteration.search_attempts = list(outcome.get("search_attempts") or [])
+        iteration.negative_search_ids = list(outcome.get("negative_search_ids") or [])
+        iteration.evidence_gain = dict(outcome.get("evidence_gain") or {})
+
+        if valid:
+            if graph_commit is None:
+                raise ValueError("validated evidence requires single-writer graph_commit callback")
+            committed_revision = graph_commit(valid)
+            if committed_revision is not None and committed_revision > base_graph_revision:
+                iteration.new_graph_revision = committed_revision
+                iteration.decision_snapshot_id = decision_snapshot_id
+                iteration.complete(IterationStatus.COMPLETED_GAIN)
+                return StepResult(
+                    iteration,
+                    priority,
+                    "re_adjudicate",
+                    ("validated evidence appended; re-adjudication required before another research iteration",),
+                )
+            iteration.evidence_gain = {
+                **iteration.evidence_gain,
+                "duplicate_only": True,
+                "unique_eligible_evidence": 0,
+            }
+
+        iteration.complete(IterationStatus.COMPLETED_NO_GAIN)
+        combined = history + [iteration.as_dict()]
+        gap_history = [row for row in combined if history_matches_gap(row, gap)]
+        available = {item.value for item in self.strategy_types_for(gap)}
+        saturation = detect_saturation(gap_history, available_strategy_types=available)
+        empirical, reasons = transition_to_empirical(
+            dvi_band=priority.dvi_band.value,
+            decision_material=priority.decision_material,
+            unresolved=True,
+            saturation=saturation,
+            ethics_feasible=ethics_feasible,
+        )
+        if empirical:
+            iteration.status = IterationStatus.EMPIRICAL_NEEDED
+            return StepResult(iteration, priority, "empirical_evidence_needed", reasons)
+        if saturation.saturated:
+            iteration.status = IterationStatus.SEARCH_SATURATED
+            return StepResult(iteration, priority, "stop_search_saturated", saturation.rationale)
+        return StepResult(
+            iteration,
+            priority,
+            "next_iteration",
+            ("no new validated evidence in this bounded iteration",),
+        )

package/engine/autoresearch/events.py

@@ -0,0 +1,12 @@
+EVIDENCE_AUTORESEARCH_EVENTS = (
+    "autoresearch.evidence.started",
+    "autoresearch.gap.ranked",
+    "autoresearch.hypothesis.created",
+    "autoresearch.iteration.started",
+    "autoresearch.search.completed",
+    "autoresearch.iteration.no_gain",
+    "autoresearch.iteration.evidence_gain",
+    "autoresearch.saturation.detected",
+    "autoresearch.empirical_needed",
+    "autoresearch.evidence.completed",
+)

package/engine/autoresearch/gap_priority.py

@@ -0,0 +1,168 @@
+from __future__ import annotations
+from dataclasses import dataclass
+from enum import Enum
+from typing import Any
+
+
+class Band(str, Enum):
+    HIGH = "HIGH"
+    MEDIUM = "MEDIUM"
+    LOW = "LOW"
+
+
+_LEVEL = {"low": 1, "medium": 2, "high": 3, "LOW": 1, "MEDIUM": 2, "HIGH": 3}
+
+
+@dataclass(frozen=True)
+class GapPriority:
+    gap_id: str
+    dvi_band: Band
+    cost_band: Band
+    decision_material: bool
+    drivers: tuple[str, ...]
+    next_research_mode: str
+    score: int
+
+    def as_dict(self) -> dict[str, Any]:
+        return {
+            "gap_id": self.gap_id,
+            "dvi_band": self.dvi_band.value,
+            "cost_band": self.cost_band.value,
+            "decision_material": self.decision_material,
+            "drivers": list(self.drivers),
+            "next_research_mode": self.next_research_mode,
+            "score": self.score,
+        }
+
+
+def _v(value: Any, default: int = 2) -> int:
+    if isinstance(value, int):
+        return max(1, min(3, value))
+    return _LEVEL.get(str(value), default)
+
+
+def _revision_number(value: Any, *, label: str) -> int:
+    if isinstance(value, bool):
+        raise ValueError(f"{label} must be an integer graph revision")
+    try:
+        revision = int(value)
+    except (TypeError, ValueError) as exc:
+        raise ValueError(f"{label} must be an integer graph revision") from exc
+    if revision < 0:
+        raise ValueError(f"{label} must be >= 0")
+    return revision
+
+
+def _require_revision_bound_decision(
+    gap: dict[str, Any], decision: dict[str, Any] | None
+) -> None:
+    """Fail closed when a DecisionSnapshot and KnowledgeGap are from different revisions.
+
+    DVI may use the current DecisionSnapshot as a decision-sensitivity input. It
+    must never combine a stale decision with a newer gap (or vice versa), since
+    that could reorder the next research target using an obsolete boundary.
+    """
+    if not decision:
+        return
+    if "graph_revision" not in decision:
+        raise ValueError(
+            "DecisionSnapshot used for DVI must include graph_revision"
+        )
+    if "derived_from_graph_revision" not in gap:
+        raise ValueError(
+            f"KnowledgeGap {gap.get('gap_id', '')!r} used for DVI must include "
+            "derived_from_graph_revision"
+        )
+    decision_revision = _revision_number(
+        decision.get("graph_revision"), label="DecisionSnapshot.graph_revision"
+    )
+    gap_revision = _revision_number(
+        gap.get("derived_from_graph_revision"),
+        label="KnowledgeGap.derived_from_graph_revision",
+    )
+    if decision_revision != gap_revision:
+        raise ValueError(
+            "stale DecisionSnapshot for DVI: "
+            f"decision revision {decision_revision} != gap revision {gap_revision}"
+        )
+
+
+def _decision_material(gap: dict[str, Any]) -> bool:
+    """Return a conservative, separately auditable materiality judgment.
+
+    Materiality is intentionally not derived from the DVI band. An explicit
+    boolean on the gap (or extensions.decision_material) wins. Otherwise only
+    gap types that can directly block/reverse an education decision are treated
+    as material by default.
+    """
+    explicit = gap.get("decision_material")
+    if isinstance(explicit, bool):
+        return explicit
+    extensions = gap.get("extensions")
+    if isinstance(extensions, dict) and isinstance(extensions.get("decision_material"), bool):
+        return bool(extensions["decision_material"])
+    return str(gap.get("gap_type", "")) in {
+        "missing_transfer",
+        "missing_retention",
+        "unresolved_conflict",
+        "weak_causal_identification",
+    }
+
+
+def rank_gap(
+    gap: dict[str, Any],
+    *,
+    decision: dict[str, Any] | None = None,
+    expected_evidence_availability: str = "medium",
+    research_cost: str = "medium",
+    applicability_relevance: str = "medium",
+    risk_irreversibility: str = "medium",
+) -> GapPriority:
+    """Return an explainable ordinal research-priority band.
+
+    This is a conceptual DVI heuristic, not EVPI/EVSI and not a probability.
+    Decision materiality is a separate field and must not be inferred from the
+    resulting DVI band when deciding whether to bridge to empirical research.
+    """
+    _require_revision_bound_decision(gap, decision)
+    decision = decision or {}
+    priority = _v(gap.get("priority", "medium"))
+    gap_type = str(gap.get("gap_type", ""))
+    material = _decision_material(gap)
+    decision_sensitive = 3 if material else priority
+    current_uncertainty = 3 if gap_type.startswith("missing_") or gap_type == "unresolved_conflict" else 2
+    directness_deficit = 3 if gap_type in {"missing_transfer", "missing_retention", "missing_outcome"} else 2
+    applicability = _v(applicability_relevance)
+    availability = _v(expected_evidence_availability)
+    cost = _v(research_cost)
+    risk = _v(risk_irreversibility)
+    score = decision_sensitive + current_uncertainty + directness_deficit + applicability + availability + risk - cost
+    if decision.get("recommended_action") in {"adopt", "ADOPT"} and gap_type in {"missing_transfer", "missing_retention"}:
+        score += 2
+    band = Band.HIGH if score >= 13 else Band.MEDIUM if score >= 9 else Band.LOW
+    cost_band = Band.HIGH if cost == 3 else Band.MEDIUM if cost == 2 else Band.LOW
+    drivers = (
+        f"gap_type={gap_type or 'unknown'}",
+        f"decision_material={material}",
+        f"decision_sensitivity={decision_sensitive}",
+        f"current_uncertainty={current_uncertainty}",
+        f"directness_deficit={directness_deficit}",
+        f"applicability_relevance={applicability}",
+        f"expected_evidence_availability={availability}",
+        f"risk_irreversibility={risk}",
+        f"research_cost={cost}",
+    )
+    mode = "secondary_evidence_search" if band is not Band.LOW else "defer"
+    return GapPriority(
+        str(gap.get("gap_id", "")),
+        band,
+        cost_band,
+        material,
+        drivers,
+        mode,
+        score,
+    )
+
+
+def rank_gaps(gaps: list[dict[str, Any]], **kwargs: Any) -> list[GapPriority]:
+    return sorted((rank_gap(g, **kwargs) for g in gaps), key=lambda x: (-x.score, x.gap_id))

package/engine/autoresearch/projection.py

@@ -0,0 +1,30 @@
+from __future__ import annotations
+from typing import Any
+from .gap_priority import rank_gaps
+from .saturation import detect_saturation
+
+
+def research_loop_projection(
+    *,
+    decision: dict[str, Any] | None,
+    gaps: list[dict[str, Any]],
+    iterations: list[dict[str, Any]],
+    revision: int,
+) -> dict[str, Any]:
+    """Projection-only state for Research Studio; never mutates canonical state."""
+    ranked = [item.as_dict() for item in rank_gaps(gaps, decision=decision)]
+    current = iterations[-1] if iterations else None
+    saturation = detect_saturation(iterations)
+    return {
+        "graph_revision": revision,
+        "decision": decision or {},
+        "gap_priorities": ranked,
+        "current_iteration": current,
+        "saturation": {
+            "saturated": saturation.saturated,
+            "low_yield_streak": saturation.low_yield_streak,
+            "strategy_diversity_exhausted": saturation.strategy_diversity_exhausted,
+            "rationale": list(saturation.rationale),
+        },
+        "iteration_count": len(iterations),
+    }