feat: add bounded feedback ranking signal

Author: whut09

src/core/ranker.ts

@@ -147,6 +147,7 @@ export interface ContextRegistryRankOptions {
   source?: string;
   tags?: string[];
   negativeExamples?: string[];
+  localQualitySignals?: Record<string, number>;
 }
 
 export interface RankedContextEntry {
@@ -181,11 +182,12 @@ export function rankContextEntry(task: string, terms: string[], entry: ContextEn
   const dependency = fieldScore(terms, (entry.dependencyChain ?? []).join(" "), 10);
   const source = sourceWeight(entry.trustLevel);
   const quality = Math.min(10, entry.qualityScore ?? qualityScore(entry));
+  const localFeedback = Math.max(-3, Math.min(3, options.localQualitySignals?.[feedbackKey(entry)] ?? 0));
   const regression = regressionWeight(terms, entry);
   const negativePenalty = negativePenaltyForEntry(entry, options.negativeExamples ?? []);
   const exactBoost = exactId ? 1000 : 0;
   const taskType = taskTypeWeight(options.taskType, entry.kind);
-  const score = exactBoost + lexical + symbol + dependency + source + quality + regression + taskType - negativePenalty;
+  const score = exactBoost + lexical + symbol + dependency + source + quality + localFeedback + regression + taskType - negativePenalty;
   const scoreBreakdown: RetrievalScoreBreakdown = {
     lexical,
     path: 0,
@@ -200,13 +202,22 @@ export function rankContextEntry(task: string, terms: string[], entry: ContextEn
     dependency,
     source,
     quality,
+    localFeedback,
     regression,
     exactId: exactBoost,
     total: score
   };
   return { entry, score, scoreBreakdown, exactId };
 }
 
+export function contextEntryFeedbackKey(entry: Pick<ContextEntry, "sourceName" | "id">): string {
+  return `${entry.sourceName}\0${entry.id}`;
+}
+
+function feedbackKey(entry: ContextEntry): string {
+  return contextEntryFeedbackKey(entry);
+}
+
 export function matchesEntryFilters(entry: ContextEntry, options: ContextRegistryRankOptions): boolean {
   if (options.packageVersion && entry.packageVersion !== options.packageVersion) return false;
   if (options.language && entry.language !== options.language) return false;

src/retrievers/context-registry.ts

@@ -19,7 +19,8 @@ export class ContextRegistryRetriever implements ContextRetriever {
       language: options.language,
       source: options.source,
       tags: options.tags,
-      negativeExamples: options.negativeExamples
+      negativeExamples: options.negativeExamples,
+      localQualitySignals: options.localQualitySignals
     });
     return ranked.slice(0, Math.max(1, options.topK)).map(({ entry, score, scoreBreakdown, exactId }) => {
       const relatedFiles = entry.files.map((file) => `context://${entry.sourceName}/${file.path}`).sort();

src/retrievers/ripgrep.ts

@@ -96,6 +96,7 @@ function hitFor(file: IndexedFile, source: "ripgrep"): ContextHit {
         dependency: 0,
         source: 0,
         quality: 0,
+        localFeedback: 0,
         regression: 0,
         exactId: 0,
         total: 0

src/retrievers/static.ts

@@ -60,6 +60,7 @@ export class StaticContextRetriever implements ContextRetriever {
               dependency: chainBoost,
               source: 0,
               quality: 0,
+              localFeedback: 0,
               regression: regressionBoost,
               exactId: 0,
               total: score
@@ -207,6 +208,7 @@ export function mergeScoreBreakdowns(left: RetrievalScoreBreakdown | undefined,
     dependency,
     source: value("source"),
     quality: value("quality"),
+    localFeedback: value("localFeedback"),
     regression,
     exactId: value("exactId"),
     total:
@@ -220,6 +222,7 @@ export function mergeScoreBreakdowns(left: RetrievalScoreBreakdown | undefined,
       regression +
       value("source") +
       value("quality") +
+      value("localFeedback") +
       value("exactId") -
       negativePenalty
   };

src/retrievers/types.ts

@@ -16,6 +16,7 @@ export interface RetrievalScoreBreakdown {
   dependency: number;
   source: number;
   quality: number;
+  localFeedback: number;
   regression: number;
   exactId: number;
   total: number;
@@ -32,6 +33,7 @@ export interface ContextRetrieverOptions {
   language?: string;
   source?: string;
   tags?: string[];
+  localQualitySignals?: Record<string, number>;
 }
 
 export function adaptiveTopK(taskType: RetrievalTaskType = "auto", requested?: number): number {

test/retrievers.test.ts

@@ -205,6 +205,18 @@ test("registry retrieval is stable for equal scores and applies negative penalty
   assert.equal(penalized.at(-1)?.metadata.scoreBreakdown?.negativePenalty, 40);
 });
 
+test("local feedback quality is opt-in, bounded, and cannot override exact ID", async () => {
+  const retriever = new ContextRegistryRetriever([registryEntry("community", "alpha", { qualityScore: 0 }), registryEntry("community", "zeta", { qualityScore: 0 })]);
+  const baseline = await retriever.search("", { topK: 10 });
+  assert.deepEqual(baseline.map((hit) => hit.id), ["community/alpha", "community/zeta"]);
+  assert.equal(baseline[0]?.metadata.scoreBreakdown?.localFeedback, 0);
+  const weighted = await retriever.search("", { topK: 10, localQualitySignals: { "community\0community/zeta": 50 } });
+  assert.equal(weighted[0]?.id, "community/zeta");
+  assert.equal(weighted[0]?.metadata.scoreBreakdown?.localFeedback, 3);
+  const exact = await retriever.search("community/alpha", { topK: 10, localQualitySignals: { "community\0community/zeta": 50, "community\0community/alpha": -50 } });
+  assert.equal(exact[0]?.id, "community/alpha");
+});
+
 test("registry retrieval reports useful precision and recall at top K", async () => {
   const retriever = new ContextRegistryRetriever([
     registryEntry("official", "session-timeout"),