docorbit 0.1.0 → 0.1.1

package/dist/packages/retrieval/src/intent.js

@@ -0,0 +1,39 @@
+const INTENT_PATTERNS = [
+    {
+        intent: 'troubleshooting',
+        regex: /\b(error|failed|failure|exception|crash|fix|debug|issue|cannot|unable|why does|broken|invalid|429|401|403|404|500)\b/i,
+    },
+    {
+        intent: 'examples',
+        regex: /\b(example|examples|sample|samples|snippet|snippets|tutorial|how to|quickstart)\b/i,
+    },
+    {
+        intent: 'configuration',
+        regex: /\b(config|configuration|settings|setup|env|\.env|environment|options|flags?|port|credentials|apikey|api_key)\b/i,
+    },
+    {
+        intent: 'api',
+        regex: /\b(api|endpoint|endpoints|parameters?|request|response|headers?|payload|schema|rest|graphql|status code)\b/i,
+    },
+    {
+        intent: 'implementation',
+        regex: /\b(implement|implementation|build|create|integrate|integration|workflow|handler|webhook|callback|oauth|pipeline)\b/i,
+    },
+    {
+        intent: 'conceptual',
+        regex: /\b(architecture|overview|what is|concept|concepts|design|lifecycle|philosophy|background|understand)\b/i,
+    },
+];
+/**
+ * Deterministically detects query intent from task or query text.
+ * Falls back to 'conceptual' when no specific pattern matches.
+ */
+export function detectQueryIntent(query) {
+    const normalized = query.toLowerCase();
+    for (const { intent, regex } of INTENT_PATTERNS) {
+        if (regex.test(normalized)) {
+            return intent;
+        }
+    }
+    return 'conceptual';
+}

package/dist/packages/retrieval/src/packer.d.ts

@@ -0,0 +1,2 @@
+import type { SearchResult, ContextPackage, ContextOptions, QueryIntent } from '../../shared/src/index.ts';
+export declare function packContext(task: string, candidates: SearchResult[], detectedIntent: QueryIntent, options?: ContextOptions): ContextPackage;

package/dist/packages/retrieval/src/packer.js

@@ -0,0 +1,108 @@
+export function packContext(task, candidates, detectedIntent, options = {}) {
+    const tokenBudget = options.tokenBudget || 3000;
+    const maxChunks = options.maxChunks || 15;
+    const redundancyPenalty = options.redundancyPenalty ?? 0.35;
+    const selectedChunks = [];
+    const selectedChunkIds = new Set();
+    const selectedSectionCounts = new Map();
+    const selectedPages = new Set();
+    const sourcesSet = new Set();
+    const warnings = [];
+    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();
+    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 = [];
+    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/dist/packages/retrieval/src/recipe-engine.d.ts

@@ -0,0 +1,18 @@
+import type { Recipe } from '../../shared/src/index.ts';
+import { DocOrbitRepository } from '../../storage/src/index.ts';
+import { RetrievalEngine } from './engine.ts';
+export interface RecipeOptions {
+    docVersion?: string;
+    projectDir?: string;
+}
+export declare class RecipeEngine {
+    private repository;
+    private retrievalEngine;
+    constructor(repository: DocOrbitRepository, retrievalEngine?: RetrievalEngine);
+    /**
+     * 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.
+     */
+    assembleRecipe(goal: string, options?: RecipeOptions): Promise<Recipe>;
+}

package/dist/packages/retrieval/src/recipe-engine.js

@@ -0,0 +1,265 @@
+import { createHash } from 'node:crypto';
+import { RetrievalEngine } from "./engine.js";
+import { resolveProjectContext } from "../../workspace/src/index.js";
+export class RecipeEngine {
+    repository;
+    retrievalEngine;
+    constructor(repository, 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, options = {}) {
+        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();
+        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 = [];
+        // 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 = [];
+        const usedApis = new Set();
+        const usedExamples = new Set();
+        const usedPitfalls = new Set();
+        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 = [];
+            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 = [];
+        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/dist/packages/retrieval/src/scorer.d.ts

@@ -0,0 +1,13 @@
+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 declare function scoreChunkCandidate(input: ScoreCandidateInput): SearchResult;

package/dist/packages/retrieval/src/scorer.js

@@ -0,0 +1,110 @@
+export function scoreChunkCandidate(input) {
+    const { chunk, ftsRank, symbols, codeSnippets, query, intent, authority = 'official', targetDocVersion, weights } = input;
+    const matchReasons = [];
+    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/dist/packages/retrieval/src/weights.d.ts

@@ -0,0 +1,3 @@
+import type { ScoringWeights } from '../../shared/src/index.ts';
+export declare const DEFAULT_SCORING_WEIGHTS_V1: ScoringWeights;
+export declare function resolveScoringWeights(overrides?: Partial<ScoringWeights>): ScoringWeights;

package/dist/packages/retrieval/src/weights.js

@@ -0,0 +1,28 @@
+export const DEFAULT_SCORING_WEIGHTS_V1 = {
+    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) {
+    if (!overrides) {
+        return { ...DEFAULT_SCORING_WEIGHTS_V1 };
+    }
+    return {
+        ...DEFAULT_SCORING_WEIGHTS_V1,
+        ...overrides,
+        authorityWeights: {
+            ...DEFAULT_SCORING_WEIGHTS_V1.authorityWeights,
+            ...(overrides.authorityWeights || {}),
+        },
+    };
+}

package/dist/packages/security/src/annotations.d.ts

@@ -0,0 +1,10 @@
+import type { SecurityAnnotation } from '../../shared/src/index.ts';
+/**
+ * Scans documentation content for security hazards (prompt injection,
+ * malicious execution snippets, unsafe links, credential harvesting) and returns
+ * non-destructive annotations.
+ *
+ * Principle: External documentation is treated as untrusted data and structurally
+ * separated from agent instructions. Original documentation text is never altered.
+ */
+export declare function detectSecurityAnnotations(content: string): SecurityAnnotation[];