docorbit 0.1.0

package/packages/retrieval/src/packer.ts

@@ -0,0 +1,145 @@
+import type {
+  SearchResult,
+  DocumentChunk,
+  ContextPackage,
+  ContextOptions,
+  QueryIntent,
+} from '../../shared/src/index.ts';
+
+export function packContext(
+  task: string,
+  candidates: SearchResult[],
+  detectedIntent: QueryIntent,
+  options: ContextOptions = {}
+): ContextPackage {
+  const tokenBudget = options.tokenBudget || 3000;
+  const maxChunks = options.maxChunks || 15;
+  const redundancyPenalty = options.redundancyPenalty ?? 0.35;
+
+  const selectedChunks: DocumentChunk[] = [];
+  const selectedChunkIds = new Set<string>();
+  const selectedSectionCounts = new Map<string, number>();
+  const selectedPages = new Set<string>();
+  const sourcesSet = new Set<string>();
+  const warnings: string[] = [];
+
+  let totalEstimatedTokens = 0;
+  const remainingCandidates = [...candidates];
+
+  while (remainingCandidates.length > 0 && selectedChunks.length < maxChunks) {
+    let bestIdx = -1;
+    let bestUtility = -Infinity;
+
+    for (let i = 0; i < remainingCandidates.length; i++) {
+      const candidate = remainingCandidates[i];
+      const chunk = candidate.chunk;
+
+      // Check if it strictly fits within the remaining token budget
+      if (totalEstimatedTokens + chunk.tokenEstimate > tokenBudget) {
+        continue;
+      }
+
+
+      const sectionKey = `${chunk.pageId}:${chunk.sectionPath.join(' > ')}`;
+      const sectionOverlap = selectedSectionCounts.get(sectionKey) || 0;
+
+      // Penalize multiple chunks from the exact same section to encourage diversity/coverage
+      const redundancyFactor = Math.pow(1 - redundancyPenalty, sectionOverlap);
+
+      // Reward discovering new pages / sections (coverage bonus)
+      const coverageMultiplier = selectedPages.has(chunk.pageId) ? 1.0 : 1.25;
+
+      const utility = candidate.score * redundancyFactor * coverageMultiplier;
+
+      if (utility > bestUtility) {
+        bestUtility = utility;
+        bestIdx = i;
+      }
+    }
+
+    if (bestIdx === -1) {
+      // No remaining candidate fits within the remaining token budget
+      break;
+    }
+
+    const chosen = remainingCandidates.splice(bestIdx, 1)[0];
+    const chunk = chosen.chunk;
+
+    selectedChunks.push(chunk);
+    selectedChunkIds.add(chunk.id);
+
+    const sectionKey = `${chunk.pageId}:${chunk.sectionPath.join(' > ')}`;
+    selectedSectionCounts.set(sectionKey, (selectedSectionCounts.get(sectionKey) || 0) + 1);
+    selectedPages.add(chunk.pageId);
+
+    if (chunk.provenance?.targetUrl) {
+      sourcesSet.add(chunk.provenance.targetUrl);
+    } else if (chunk.provenance?.sourceUrl) {
+      sourcesSet.add(chunk.provenance.sourceUrl);
+    }
+
+    totalEstimatedTokens += chunk.tokenEstimate;
+
+    // If chunk is a warning, register it in top-level warnings
+    if (chunk.chunkType === 'warning') {
+      warnings.push(`[${chunk.sectionPath.join(' > ')}]: ${chunk.content.slice(0, 150)}...`);
+    }
+  }
+
+  // Group chunks by page in order of page first appearance in selectedChunks (most relevant page first)
+  const pageOrder = new Map<string, number>();
+  for (let i = 0; i < selectedChunks.length; i++) {
+    const pId = selectedChunks[i].pageId;
+    if (!pageOrder.has(pId)) {
+      pageOrder.set(pId, pageOrder.size);
+    }
+  }
+
+  const sortedChunks = [...selectedChunks].sort((a, b) => {
+    const pOrderA = pageOrder.get(a.pageId) ?? 0;
+    const pOrderB = pageOrder.get(b.pageId) ?? 0;
+    if (pOrderA !== pOrderB) return pOrderA - pOrderB;
+    return a.ordinal - b.ordinal;
+  });
+
+  // Build agent-facing Markdown package
+  const lines: string[] = [];
+  lines.push(`# Context Package: ${task}`);
+  lines.push(`- **Detected Intent**: \`${detectedIntent}\``);
+  lines.push(`- **Estimated Tokens**: ~${totalEstimatedTokens} / ${tokenBudget} tokens (heuristic estimate)`);
+  lines.push(`- **Sources Included**: ${sourcesSet.size > 0 ? Array.from(sourcesSet).map(s => `[${s}](${s})`).join(', ') : 'Local documentation'}`);
+
+  if (warnings.length > 0) {
+    lines.push('\n> [!WARNING]');
+    lines.push('> **Relevant Advisories & Caveats**:');
+    for (const w of warnings) {
+      lines.push(`> - ${w}`);
+    }
+  }
+
+  lines.push('\n---\n');
+
+  for (const chunk of sortedChunks) {
+    const breadcrumb = chunk.sectionPath.length > 0 ? chunk.sectionPath.join(' > ') : (chunk.title || 'General');
+    lines.push(`### ${breadcrumb}`);
+    lines.push(`*Type: \`${chunk.chunkType}\` | Est. Tokens: ~${chunk.tokenEstimate}*`);
+    lines.push('\n' + chunk.content.trim() + '\n');
+    if (chunk.provenance?.sourceUrl) {
+      lines.push(`*Source: ${chunk.provenance.sourceUrl}*\n`);
+    }
+    lines.push('---\n');
+  }
+
+  const markdown = lines.join('\n');
+
+  return {
+    task,
+    detectedIntent,
+    totalEstimatedTokens,
+    tokenBudget,
+    chunks: sortedChunks,
+    markdown,
+    sources: Array.from(sourcesSet),
+    warnings,
+  };
+}

package/packages/retrieval/src/recipe-engine.ts

@@ -0,0 +1,313 @@
+import { createHash } from 'node:crypto';
+import type {
+  Recipe,
+  RecipeStep,
+  RecipeValidationStep,
+  EvidenceLevel,
+  ApiEndpoint,
+  IndexedExample,
+  Pitfall,
+} from '../../shared/src/index.ts';
+import { DocOrbitRepository } from '../../storage/src/index.ts';
+import { RetrievalEngine } from './engine.ts';
+import { resolveProjectContext } from '../../workspace/src/index.ts';
+
+export interface RecipeOptions {
+  docVersion?: string;
+  projectDir?: string;
+}
+
+export class RecipeEngine {
+  private repository: DocOrbitRepository;
+  private retrievalEngine: RetrievalEngine;
+
+  constructor(repository: DocOrbitRepository, retrievalEngine?: RetrievalEngine) {
+    this.repository = repository;
+    this.retrievalEngine = retrievalEngine || new RetrievalEngine(repository);
+  }
+
+  /**
+   * Deterministically compiles an implementation recipe grounded strictly in indexed evidence.
+   * Distinguishes documented facts, inferred relationships, and missing information.
+   * Never invents APIs, steps, prerequisites, or validation steps.
+   */
+  async assembleRecipe(goal: string, options: RecipeOptions = {}): Promise<Recipe> {
+    const cleanGoal = goal.trim();
+    let effectiveDocVersion = options.docVersion;
+
+    // Resolve project and version context if projectDir is provided
+    if (options.projectDir) {
+      const projContext = resolveProjectContext(options.projectDir, cleanGoal, this.repository);
+      if (projContext.matchedDependency && !effectiveDocVersion) {
+        effectiveDocVersion = projContext.matchedDependency.targetDocVersion;
+      }
+    }
+
+    // 1. Query candidate API endpoints, examples, pitfalls, and search chunks
+    const endpoints = this.repository.searchApiEndpoints(cleanGoal, {
+      docVersion: effectiveDocVersion,
+      limit: 10,
+    });
+
+    const examples = this.repository.searchIndexedExamples(cleanGoal, {
+      docVersion: effectiveDocVersion,
+      limit: 10,
+    });
+
+    const pitfalls = this.repository.searchPitfalls(cleanGoal, {
+      docVersion: effectiveDocVersion,
+      limit: 10,
+    });
+
+    const searchResults = await this.retrievalEngine.search(cleanGoal, {
+      docVersion: effectiveDocVersion,
+      limit: 10,
+    });
+
+    // 2. Collect unique source URLs
+    const sourcesSet = new Set<string>();
+    for (const ep of endpoints) {
+      if (ep.provenance?.sourceUrl) sourcesSet.add(ep.provenance.sourceUrl);
+    }
+    for (const ex of examples) {
+      if (ex.sourceUrl) sourcesSet.add(ex.sourceUrl);
+    }
+    for (const pf of pitfalls) {
+      if (pf.provenance?.sourceUrl) sourcesSet.add(pf.provenance.sourceUrl);
+    }
+    for (const sr of searchResults) {
+      if (sr.chunk.provenance?.sourceUrl) sourcesSet.add(sr.chunk.provenance.sourceUrl);
+    }
+    const sources = Array.from(sourcesSet);
+
+    // 3. Assemble Prerequisites strictly from documented requirements
+    const prerequisites: Array<{ text: string; evidenceLevel: EvidenceLevel; sourceUrl?: string }> = [];
+
+    // Check required_config or permission pitfalls
+    for (const pf of pitfalls) {
+      if (pf.kind === 'required_config' || pf.kind === 'permission') {
+        prerequisites.push({
+          text: `${pf.title}: ${pf.content}`,
+          evidenceLevel: 'documented_fact',
+          sourceUrl: pf.provenance?.sourceUrl,
+        });
+      }
+    }
+
+    // Check chunks with prerequisite/setup headings (only relevant chunks with score >= 5.0)
+    for (const sr of searchResults.filter(s => s.score >= 5.0)) {
+      const headingText = (sr.chunk.title || sr.chunk.sectionPath.join(' ')).toLowerCase();
+      if (headingText.includes('prerequisite') || headingText.includes('before you begin') || headingText.includes('requirements')) {
+        const textSnippet = sr.chunk.content.split('\n')[0].trim();
+        if (textSnippet && !prerequisites.some(p => p.text === textSnippet)) {
+          prerequisites.push({
+            text: textSnippet,
+            evidenceLevel: 'documented_fact',
+            sourceUrl: sr.chunk.provenance?.sourceUrl,
+          });
+        }
+      }
+    }
+
+    // 4. Assemble Ordered Steps
+    const orderedSteps: RecipeStep[] = [];
+    const usedApis = new Set<string>();
+    const usedExamples = new Set<string>();
+    const usedPitfalls = new Set<string>();
+    let stepNumber = 1;
+
+    // A. Setup / Client Initialization Step (if documented in examples)
+    const initExample = examples.find(ex =>
+      /(?:new\s+\w+|initialize|config(?:ure)?|createClient|express\(\)|FastAPI\()/i.test(ex.code)
+    );
+    if (initExample) {
+      orderedSteps.push({
+        step: stepNumber++,
+        title: `Initialize Client / Service (${initExample.framework || initExample.language})`,
+        description: `Configure and initialize client instance as documented in ${initExample.task}`,
+        evidenceLevel: 'documented_fact',
+        exampleCode: initExample.code,
+        sourceUrl: initExample.sourceUrl,
+        sourceChunkIds: initExample.chunkId ? [initExample.chunkId] : undefined,
+      });
+      usedExamples.add(initExample.id);
+    }
+
+    // B. Primary API Actions (Documented Fact)
+    for (const ep of endpoints) {
+      const apiStr = `${ep.method.toUpperCase()} ${ep.path}`;
+      if (usedApis.has(apiStr)) continue;
+      usedApis.add(apiStr);
+
+      // Find matching code example for this API
+      const matchingEx = examples.find(ex =>
+        !usedExamples.has(ex.id) &&
+        (ex.relatedApi === apiStr || ex.code.includes(ep.path) || (ep.operationId && ex.code.includes(ep.operationId)))
+      );
+      if (matchingEx) usedExamples.add(matchingEx.id);
+
+      // Find matching pitfalls for this API
+      const matchingPfs = pitfalls.filter(pf =>
+        pf.relatedApi === apiStr ||
+        (ep.deprecated && pf.kind === 'deprecated') ||
+        (pf.kind === 'rate_limit') ||
+        (pf.kind === 'breaking_change')
+      );
+      const stepPitfalls: string[] = [];
+      for (const p of matchingPfs) {
+        const pfStr = `[${p.kind}] ${p.title}: ${p.content}`;
+        stepPitfalls.push(pfStr);
+        usedPitfalls.add(pfStr);
+      }
+
+      // If the endpoint is deprecated, explicitly highlight it in step title/description
+      const depWarning = ep.deprecated ? ' [DEPRECATED]' : '';
+
+      orderedSteps.push({
+        step: stepNumber++,
+        title: `${apiStr}${depWarning}${ep.summary ? ` - ${ep.summary}` : ''}`,
+        description: ep.description || ep.summary || `Execute documented ${apiStr} request with parameters: ${ep.parameters.map(p => `${p.name}${p.required ? ' (required)' : ''}`).join(', ')}`,
+        evidenceLevel: 'documented_fact',
+        apiEndpoint: apiStr,
+        exampleCode: matchingEx?.code,
+        pitfalls: stepPitfalls.length > 0 ? stepPitfalls : undefined,
+        sourceUrl: ep.provenance?.sourceUrl || matchingEx?.sourceUrl,
+        sourceChunkIds: matchingEx?.chunkId ? [matchingEx.chunkId] : undefined,
+      });
+    }
+
+    // C. Remaining Code Examples as implementation steps
+    for (const ex of examples) {
+      if (usedExamples.has(ex.id)) continue;
+      usedExamples.add(ex.id);
+
+      const matchingPfs = pitfalls.filter(pf =>
+        (ex.relatedApi && pf.relatedApi === ex.relatedApi) ||
+        (ex.relatedSymbol && pf.relatedSymbol === ex.relatedSymbol)
+      );
+      const stepPitfalls = matchingPfs.map(p => `[${p.kind}] ${p.title}: ${p.content}`);
+      stepPitfalls.forEach(p => usedPitfalls.add(p));
+
+      orderedSteps.push({
+        step: stepNumber++,
+        title: ex.task,
+        description: `Implement documented code example for ${ex.task} (${ex.language}${ex.framework ? ` / ${ex.framework}` : ''})`,
+        evidenceLevel: 'documented_fact',
+        apiEndpoint: ex.relatedApi,
+        exampleCode: ex.code,
+        pitfalls: stepPitfalls.length > 0 ? stepPitfalls : undefined,
+        sourceUrl: ex.sourceUrl,
+        sourceChunkIds: ex.chunkId ? [ex.chunkId] : undefined,
+      });
+
+      if (ex.relatedApi) usedApis.add(ex.relatedApi);
+    }
+
+    // D. If neither endpoints nor examples existed, check procedural chunks with strong relevance
+    if (orderedSteps.length === 0) {
+      for (const sr of searchResults.filter(s => s.score >= 5.0).slice(0, 3)) {
+        orderedSteps.push({
+          step: stepNumber++,
+          title: sr.chunk.title || sr.chunk.sectionPath.join(' > ') || 'Documented Procedure',
+          description: sr.chunk.content.substring(0, 300),
+          evidenceLevel: 'inferred_relationship',
+          sourceUrl: sr.chunk.provenance?.sourceUrl,
+          sourceChunkIds: [sr.chunk.id],
+        });
+      }
+    }
+
+    // E. If documentation contains no relevant implementation steps, mark missing_information
+    if (orderedSteps.length === 0) {
+      orderedSteps.push({
+        step: stepNumber++,
+        title: 'Missing Implementation Knowledge',
+        description: `The indexed documentation does not contain documented API endpoints, code examples, or procedures for: "${cleanGoal}".`,
+        evidenceLevel: 'missing_information',
+      });
+    }
+
+    // 5. Assemble Evidence-Based Validation Steps
+    const validationSteps: RecipeValidationStep[] = [];
+    let valStepNumber = 1;
+
+    // Validation from API response schemas
+    for (const ep of endpoints) {
+      const okResponse = ep.responseSchema?.['200'] || ep.responseSchema?.['201'];
+      if (okResponse && okResponse.schema) {
+        const props = okResponse.schema.properties ? Object.keys(okResponse.schema.properties) : [];
+        const propsDesc = props.length > 0 ? ` Expected properties: [${props.slice(0, 6).join(', ')}]` : '';
+        const exampleStr = okResponse.example ? JSON.stringify(okResponse.example, null, 2) : undefined;
+
+        validationSteps.push({
+          step: valStepNumber++,
+          description: `Verify ${ep.method.toUpperCase()} ${ep.path} returns HTTP ${okResponse.statusCode}.${propsDesc}`,
+          evidenceLevel: 'documented_fact',
+          expectedResponse: exampleStr || (props.length > 0 ? JSON.stringify(props) : undefined),
+          sourceUrl: ep.provenance?.sourceUrl,
+        });
+      }
+    }
+
+    // Validation from code examples containing verification/assertion patterns
+    for (const ex of examples) {
+      if (/(?:constructEvent|verifySignature|assert|expect|validate|signature)/i.test(ex.code)) {
+        validationSteps.push({
+          step: valStepNumber++,
+          description: `Validate event/data integrity using documented pattern from ${ex.task}`,
+          evidenceLevel: 'documented_fact',
+          testPattern: ex.code,
+          sourceUrl: ex.sourceUrl,
+        });
+      }
+    }
+
+    // If no validation steps can be derived from evidence, do NOT invent any!
+    if (validationSteps.length === 0) {
+      validationSteps.push({
+        step: 1,
+        description: 'No response schemas, test instructions, or verification assertions are documented for this task.',
+        evidenceLevel: 'missing_information',
+      });
+    }
+
+    // Collect all pitfalls
+    for (const pf of pitfalls) {
+      const pfStr = `[${pf.kind}] ${pf.title}: ${pf.content}`;
+      usedPitfalls.add(pfStr);
+    }
+
+    // Calculate confidence score strictly based on evidence
+    let confidence = 0.0;
+    const factSteps = orderedSteps.filter(s => s.evidenceLevel === 'documented_fact').length;
+    const totalSteps = orderedSteps.length;
+
+    if (totalSteps > 0 && factSteps > 0) {
+      confidence += 0.4 * (factSteps / totalSteps);
+      if (endpoints.length > 0) confidence += 0.3;
+      if (examples.length > 0) confidence += 0.2;
+      if (validationSteps.some(v => v.evidenceLevel === 'documented_fact')) confidence += 0.1;
+    }
+
+    confidence = Math.min(1.0, Math.round(confidence * 100) / 100);
+
+    const recipeId = createHash('sha256')
+      .update(`${cleanGoal}:${effectiveDocVersion || 'default'}:${orderedSteps.length}`)
+      .digest('hex')
+      .substring(0, 16);
+
+    return {
+      id: recipeId,
+      goal: cleanGoal,
+      prerequisites,
+      orderedSteps,
+      requiredApis: Array.from(usedApis),
+      examples: Array.from(usedExamples),
+      pitfalls: Array.from(usedPitfalls),
+      validationSteps,
+      sources,
+      docVersion: effectiveDocVersion,
+      confidence,
+    };
+  }
+}

package/packages/retrieval/src/scorer.ts

@@ -0,0 +1,139 @@
+import type {
+  DocumentChunk,
+  SymbolReference,
+  ChunkCode,
+  ScoringWeights,
+  QueryIntent,
+  SourceAuthority,
+  SearchResult,
+} from '../../shared/src/index.ts';
+
+export interface ScoreCandidateInput {
+  chunk: DocumentChunk;
+  ftsRank: number;
+  symbols: SymbolReference[];
+  codeSnippets: ChunkCode[];
+  query: string;
+  intent: QueryIntent;
+  authority?: SourceAuthority;
+  targetDocVersion?: string;
+  weights: ScoringWeights;
+}
+
+export function scoreChunkCandidate(input: ScoreCandidateInput): SearchResult {
+  const { chunk, ftsRank, symbols, codeSnippets, query, intent, authority = 'official', targetDocVersion, weights } = input;
+
+  const matchReasons: string[] = [];
+  const queryLower = query.toLowerCase().trim();
+  const queryTokens = queryLower
+    .replace(/[^\w\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > 2);
+
+  // 1. Base BM25 score from FTS5 (FTS5 rank is negative where smaller = more relevant)
+  const normalizedBm25 = Math.max(0.1, -ftsRank);
+  let totalScore = normalizedBm25 * weights.bm25Weight;
+  matchReasons.push(`BM25 base (${normalizedBm25.toFixed(2)})`);
+
+  // 2. Exact phrase match in content
+  if (chunk.content.toLowerCase().includes(queryLower)) {
+    totalScore += weights.exactPhraseBonus;
+    matchReasons.push(`Exact phrase match (+${weights.exactPhraseBonus})`);
+  }
+
+  // 3. Title match
+  const titleLower = (chunk.title || '').toLowerCase();
+  const titleMatches = queryTokens.filter(t => titleLower.includes(t));
+  if (titleMatches.length > 0) {
+    const boost = weights.titleBonus * (titleMatches.length / queryTokens.length);
+    totalScore += boost;
+    matchReasons.push(`Title match [${titleMatches.join(', ')}] (+${boost.toFixed(1)})`);
+  }
+
+  // 4. Section path match
+  const pathString = chunk.sectionPath.join(' ').toLowerCase();
+  const pathMatches = queryTokens.filter(t => pathString.includes(t));
+  if (pathMatches.length > 0) {
+    const boost = weights.sectionPathBonus * (pathMatches.length / queryTokens.length);
+    totalScore += boost;
+    matchReasons.push(`Section breadcrumbs match [${pathMatches.join(', ')}] (+${boost.toFixed(1)})`);
+  }
+
+  // 5. Symbol match (shallow deterministic regex symbols)
+  const matchedSymbols = symbols.filter(s => {
+    const symLower = s.name.toLowerCase();
+    return queryLower.includes(symLower) || symLower.includes(queryLower);
+  });
+  if (matchedSymbols.length > 0) {
+    totalScore += weights.symbolMatchBonus;
+    matchReasons.push(`Symbol match [${matchedSymbols.map(s => s.name).join(', ')}] (+${weights.symbolMatchBonus})`);
+  }
+
+  // 6. Query intent alignment
+  let intentBoost = 0;
+  if (intent === 'api' && chunk.chunkType === 'api') {
+    intentBoost = weights.intentTypeBonus;
+  } else if (intent === 'examples' && (chunk.chunkType === 'example' || chunk.chunkType === 'code')) {
+    intentBoost = weights.intentTypeBonus;
+  } else if (intent === 'troubleshooting' && (chunk.chunkType === 'warning' || /error|exception|fail|status|code/i.test(chunk.content))) {
+    intentBoost = weights.intentTypeBonus;
+  } else if (intent === 'implementation' && (chunk.chunkType === 'mixed' || chunk.chunkType === 'example')) {
+    intentBoost = weights.intentTypeBonus;
+  } else if (intent === 'conceptual' && chunk.chunkType === 'prose') {
+    intentBoost = weights.intentTypeBonus;
+  } else if (intent === 'configuration' && (symbols.some(s => s.kind === 'config') || chunk.chunkType === 'prose')) {
+    intentBoost = weights.intentTypeBonus;
+  }
+
+  if (intentBoost > 0) {
+    totalScore += intentBoost;
+    matchReasons.push(`Intent alignment '${intent}' for chunkType '${chunk.chunkType}' (+${intentBoost})`);
+  }
+
+  // 7. Documentation version boosting & nuance
+  if (targetDocVersion && chunk.docVersion) {
+    const chunkVerClean = chunk.docVersion.replace(/^[v=]/, '');
+    const targetVerClean = targetDocVersion.replace(/^[v=]/, '');
+
+    const chunkMajor = chunkVerClean.split('.')[0];
+    const targetMajor = targetVerClean.split('.')[0];
+
+    if (chunkVerClean === targetVerClean || chunk.docVersion === targetDocVersion) {
+      // Exact version match
+      totalScore += weights.versionBonus;
+      matchReasons.push(`Target doc version exact match [${chunk.docVersion}] (+${weights.versionBonus})`);
+    } else if (chunkMajor === targetMajor) {
+      // Same major version (e.g. target 14.2.3, chunk v14 or 14.1)
+      const majorBoost = weights.versionBonus * 0.85;
+      totalScore += majorBoost;
+      matchReasons.push(`Target doc major match [${chunk.docVersion}] (+${majorBoost.toFixed(1)})`);
+    } else if (
+      chunk.docVersion === 'latest' ||
+      chunk.docVersion === 'stable' ||
+      chunk.docVersion === 'current'
+    ) {
+      // Unversioned / latest documentation: neutral supplemental context
+      matchReasons.push(`Supplemental unversioned/latest documentation [${chunk.docVersion}]`);
+    } else {
+      // Evidence of major version incompatibility (e.g. target v14 vs chunk v16)
+      const penalty = weights.versionBonus * 0.5;
+      totalScore -= penalty;
+      matchReasons.push(`Version major discrepancy [chunk ${chunk.docVersion} vs target ${targetDocVersion}] (-${penalty.toFixed(1)})`);
+    }
+  }
+
+  // 8. Authority weighting
+  const authMultiplier = weights.authorityWeights[authority] ?? 1.0;
+  totalScore *= authMultiplier;
+  if (authMultiplier !== 1.0) {
+    matchReasons.push(`Authority weighting: x${authMultiplier}`);
+  }
+
+  return {
+    chunk,
+    score: parseFloat(totalScore.toFixed(3)),
+    matchReasons,
+    symbols,
+    codeSnippets,
+  };
+}

package/packages/retrieval/src/weights.ts

@@ -0,0 +1,31 @@
+import type { ScoringWeights } from '../../shared/src/index.ts';
+
+export const DEFAULT_SCORING_WEIGHTS_V1: ScoringWeights = {
+  version: '1.0.0',
+  bm25Weight: 1.0,
+  exactPhraseBonus: 5.0,
+  titleBonus: 8.0,
+  sectionPathBonus: 4.0,
+  symbolMatchBonus: 10.0,
+  intentTypeBonus: 6.0,
+  versionBonus: 12.0,
+  authorityWeights: {
+    official: 1.0,
+    community: 0.8,
+    third_party: 0.6,
+  },
+};
+
+export function resolveScoringWeights(overrides?: Partial<ScoringWeights>): ScoringWeights {
+  if (!overrides) {
+    return { ...DEFAULT_SCORING_WEIGHTS_V1 };
+  }
+  return {
+    ...DEFAULT_SCORING_WEIGHTS_V1,
+    ...overrides,
+    authorityWeights: {
+      ...DEFAULT_SCORING_WEIGHTS_V1.authorityWeights,
+      ...(overrides.authorityWeights || {}),
+    },
+  };
+}