feat(s31): Retriever seam — StructuralRetriever default + HybridRanker with injected similarity

src/portfolio_optimiser/verdicts.py

@@ -28,7 +28,7 @@ from typing import Any
 
 from agent_framework import ContextProvider, SessionContext
 
-from portfolio_optimiser import okf
+from portfolio_optimiser import okf, semretrieval
 
 _log = logging.getLogger(__name__)
 
@@ -251,6 +251,11 @@ class VerdictStore:
 
     verdicts: list[Verdict]
 
+    # S3.1 opt-in seam: ``None`` means the structural default, which is byte-identical to the
+    # pre-seam inline sort. Only an explicit caller (``run.py --semantic-retrieval``) installs a
+    # different ranker, so default retrieval behaviour is unchanged.
+    retriever: semretrieval.Retriever | None = None
+
     @classmethod
     def from_dir(cls, directory: str) -> VerdictStore:
         """Build a store from an async inbox folder (convenience constructor). ``run_project`` uses
@@ -260,15 +265,20 @@ class VerdictStore:
         return cls(verdicts=load_verdicts_from_dir(directory))
 
     def retrieve(self, query: ProposalFeatures, k: int) -> list[Verdict]:
-        """Return the top-``k`` verdicts by structural similarity. Deterministic: ties break
-        by verdict id, so ordering is stable across runs."""
+        """Return the top-``k`` verdicts. Deterministic: ties break by verdict id, so ordering
+        is stable across runs.
+
+        Ranking is delegated to ``self.retriever``, defaulting to ``StructuralRetriever`` — the
+        same weighted structural score and ``(-similarity, id)`` key as before the seam existed.
+        A caller that installs a ``HybridRanker`` opts into an additional semantic term."""
         if k <= 0:
             raise ValueError(f"k must be positive, got {k}")
-        ranked = sorted(
-            self.verdicts,
-            key=lambda v: (-similarity(query, v.proposal_features), v.id),
+        ranker = (
+            self.retriever
+            if self.retriever is not None
+            else semretrieval.StructuralRetriever(similarity)
         )
-        return ranked[:k]
+        return ranker.rank(query, self.verdicts, k)
 
     def add(self, verdict: Verdict) -> None:
         """Persist a captured verdict in-memory.