@blxzer/cursor-trellis 0.1.0

package/dist/utils/codebase-retrieval-router.js

@@ -0,0 +1,767 @@
+/**
+ * Deterministic codebase retrieval intent router.
+ *
+ * Mirrors machine-readable rules from `codebase-retrieval` capability guidance
+ * in project-capabilities.ts. Produces the parent shared evidence envelope
+ * (router-owned fields only; adapterState/freshness are pass-through stubs).
+ */
+export const CODEBASE_RETRIEVAL_ROUTER_VERSION = 2;
+export const PLATFORM_CURSOR = "cursor";
+export const PLATFORM_CLAUDE_CODE = "claude-code";
+export const PLATFORM_CODEX = "codex";
+export const PLATFORM_GENERIC = "generic";
+export const KNOWN_PLATFORMS = new Set([
+    PLATFORM_CURSOR,
+    PLATFORM_CLAUDE_CODE,
+    PLATFORM_CODEX,
+    PLATFORM_GENERIC,
+]);
+export const MODALITY_LEXICAL = "lexical";
+export const MODALITY_STRUCTURAL = "structural";
+export const MODALITY_SEMANTIC = "semantic";
+export const TOKEN_ECONOMY_HIGH = "high";
+export const TOKEN_ECONOMY_MEDIUM = "medium";
+export const TOKEN_ECONOMY_LOW = "low";
+export function emptyCodebaseRetrievalPlan(query = "", platform = PLATFORM_GENERIC, projectFileCount = null) {
+    return {
+        version: CODEBASE_RETRIEVAL_ROUTER_VERSION,
+        query,
+        intents: [],
+        routes: [],
+        adapterState: [],
+        freshness: [],
+        fallback: [],
+        warnings: [],
+        verification: [],
+        platform,
+        projectFileCount,
+    };
+}
+const POLICY_SIGNALS = [
+    /\bstorage\s+policy\b/i,
+    /\bsidecar\b/i,
+    /\bsqlite\s+only\b/i,
+    /\bpersistence\b/i,
+    /\bimport\s+boundar/i,
+    /\btransport[- ]only\b/i,
+    /\barchitecture\b/i,
+    /\bconvention(s)?\b/i,
+    /\bforbidden\b/i,
+    /\ballowed\b/i,
+    /\bwhere\s+is\s+\w+\s+defined\b/i,
+    /\bwho\s+owns\b/i,
+    /\bwho\s+is\s+responsible\s+for\b/i,
+    /\bwhich\s+module\s+handles\b/i,
+    /\bwhich\s+package\s+is\s+responsible\b/i,
+    /\ballowed\s+in\b/i,
+    /\bforbidden\s+in\b/i,
+    /\brestricted\s+to\b/i,
+    /\bmust\s+not\b/i,
+    /\bshould\s+not\b/i,
+    /\bboundary\s+between\b/i,
+    /\bboundary\s+of\b/i,
+    /\bcode\s+boundary\b/i,
+    /\bmodule\s+boundary\b/i,
+    /\bpackage\s+boundary\b/i,
+    /规定/,
+    /边界/,
+    /为什么不能/,
+    /\bAGENTS\.md\b/i,
+    /\bpolicy\b/i,
+    /\bownership\b/i,
+    /\bresponsibilit(y|ies)\b/i,
+    /不能/,
+    /规则/,
+];
+const CONCEPTUAL_SIGNALS = [
+    /\bhow\s+does\b/i,
+    /\bacross\s+(packages|modules)\b/i,
+    /\bwhere\s+is\b.*\b(handled|implemented)\b/i,
+    /\bdifference\s+between\b/i,
+    /\boverall\s+design\b/i,
+    /如何/,
+    /机制/,
+    /跨/,
+    /为什么/,
+    /原理/,
+    /区别/,
+];
+const PRESERVE_SIGNALS = [
+    /\bapps\/(ios|android)\b/i,
+    /\bgateway-protocol\b/i,
+    /\bpackages\/gateway-protocol\b/i,
+    /\.swift\b/i,
+    /\.kt\b/i,
+    /\bschema\b/i,
+    /\bcontract\b/i,
+    /\bprotocol\s+constant\b/i,
+];
+const CALLER_CHAIN_SIGNALS = [
+    /\bwho\s+calls\b/i,
+    /\bwhich\s+modules?\s+invoke\b/i,
+    /\bcall\s*sites?\b/i,
+    /\bcaller(s)?\b/i,
+    /\bwired\b/i,
+    /\bdelegate(s|d)?\b/i,
+    /\bassembly\b/i,
+    /\bdependents\b/i,
+    /\busages?\s+of\b/i,
+    /谁调用/,
+    /调用链/,
+    /影响面/,
+    /被哪些/,
+    /哪些地方/,
+    /哪里用到/,
+];
+const TRAP_SIGNALS = [
+    /\bpackages\/[a-z0-9-]+\b/i,
+    /\bsrc\/agents\b/i,
+    /\btrap\b/i,
+    /\bdifferent\s+package\b/i,
+    /\blayer\b/i,
+    /\boverlay\b/i,
+    /\bcore\s+library\b/i,
+];
+const EXTENSION_SIGNALS = [
+    /\bextensions\/\b/i,
+    /\bextension\s+id\b/i,
+    /\bshared\s+symbol\b/i,
+    /\bacross\s+extensions\b/i,
+];
+const ENV_LITERAL_SIGNALS = [
+    /\bOPENCLAW_[A-Z0-9_]+\b/,
+    /\be2e\b/i,
+    /\bbench(mark)?\b/i,
+    /\benv\s+var/i,
+    /\benvironment\s+variable\b/i,
+    /\bstartup\s+script\b/i,
+];
+const EXACT_SYMBOL_SIGNALS = [
+    /\b[A-Z][a-zA-Z0-9]+(?:[A-Z][a-zA-Z0-9]+)+\b/,
+    /\b[a-z][a-zA-Z0-9]+(?:[A-Z][a-zA-Z0-9]+)+\b/,
+    /`[^`]+`/,
+    /\b[\w.-]+\.(ts|tsx|js|jsx|py|rs|go|swift|kt|md|json|yaml|yml)\b/i,
+    /\b(?:src|packages|extensions)\/[\w./-]+/i,
+];
+function normalizeQuery(query) {
+    return query.replace(/\s+/g, " ").trim();
+}
+function matchAny(patterns, text) {
+    const hits = [];
+    for (const pattern of patterns) {
+        const match = text.match(pattern);
+        if (match) {
+            hits.push(match[0]);
+        }
+    }
+    return hits;
+}
+function intentConfidence(hitCount, strong) {
+    if (strong && hitCount >= 2)
+        return "high";
+    if (hitCount >= 2)
+        return "medium";
+    if (hitCount === 1)
+        return strong ? "medium" : "low";
+    return "low";
+}
+function buildIntent(id, label, signals, confidence, preserveExactPrimary) {
+    return {
+        id,
+        label,
+        confidence,
+        signals: [...new Set(signals)].slice(0, 12),
+        preserveExactPrimary,
+    };
+}
+function baseVerification() {
+    return [
+        {
+            id: "source-read",
+            requirement: "Read current source around candidate file ranges before final claims.",
+            appliesToRoles: ["exact", "ast", "lsp", "semantic"],
+        },
+        {
+            id: "git-scope",
+            requirement: "Inspect relevant Git diff/log evidence when behavior or impact is claimed.",
+            appliesToRoles: ["verification"],
+        },
+        {
+            id: "focused-tests",
+            requirement: "Run task-appropriate validation when tests define the claim boundary.",
+            appliesToRoles: ["verification"],
+        },
+    ];
+}
+function policyVerification() {
+    return [
+        {
+            id: "policy-doc-top1",
+            requirement: "For policy/document intents, confirm Top-1 policy evidence from AGENTS.md or .trellis/spec before ranking implementation modules first.",
+            appliesToRoles: ["exact", "semantic"],
+        },
+        {
+            id: "agents-neighborhood",
+            requirement: "Read AGENTS.md neighborhood: root AGENTS.md, nested **/AGENTS.md, and package-level policy files before searching implementation modules.",
+            appliesToRoles: ["exact", "semantic"],
+        },
+        ...baseVerification(),
+    ];
+}
+function callerVerification() {
+    return [
+        {
+            id: "caller-sites",
+            requirement: "Confirm codegraph-caller results cover the call chain, then verify " +
+                "dynamic dispatch points (callbacks, event handlers, DI registrations) " +
+                "that codegraph may not resolve statically.",
+            appliesToRoles: ["exact", "ast"],
+        },
+        ...baseVerification(),
+    ];
+}
+function trapVerification() {
+    return [
+        {
+            id: "trap-package-check",
+            requirement: "When multiple same-named symbols exist across packages, confirm the " +
+                "codegraph result belongs to the correct package by checking the file's " +
+                "package root or AGENTS.md scope before ranking.",
+            appliesToRoles: ["ast", "exact"],
+        },
+        ...baseVerification(),
+    ];
+}
+function extensionVerification() {
+    return [
+        {
+            id: "extension-scope-check",
+            requirement: "Confirm the symbol definition lives inside the target extension " +
+                "directory, not in a shared core module with the same name.",
+            appliesToRoles: ["ast", "exact"],
+        },
+        ...baseVerification(),
+    ];
+}
+function routeExactPrimary(intentIds) {
+    return {
+        order: 1,
+        id: "exact-rg-primary",
+        role: "exact",
+        sourceFamily: "rg",
+        commands: ["rg <pattern> <path>"],
+        rationale: "Exact identifiers, literals, paths, and protocol constants stay primary; corroborate with direct reads.",
+        intentIds,
+    };
+}
+function routePolicyDocs(intentIds) {
+    return {
+        order: 2,
+        id: "policy-docs-rg",
+        role: "exact",
+        sourceFamily: "policy-docs",
+        commands: [
+            'rg -i "storage default|sidecar|sqlite only" AGENTS.md "**/AGENTS.md" README.md CONTRIBUTING.md .trellis/spec',
+        ],
+        rationale: "Policy/document intent: search instruction and spec docs before implementation modules.",
+        intentIds,
+    };
+}
+function routeAst(intentIds, order) {
+    return {
+        order,
+        id: "ast-codegraph",
+        role: "ast",
+        sourceFamily: "codegraph",
+        commands: [
+            "codegraph query <symbol-or-search> --path <path> --json",
+            "codegraph callers <symbol> --path <path> --json",
+            "codegraph callees <symbol> --path <path> --json",
+        ],
+        rationale: "Structural expansion after exact candidates exist; graph output remains candidate until freshness and source checks.",
+        intentIds,
+    };
+}
+function routeSemantic(intentIds, order) {
+    return {
+        order,
+        id: "semantic-fast-context",
+        role: "semantic",
+        sourceFamily: "fast-context",
+        commands: ["fast_context_search query=<question> project_path=<root>"],
+        rationale: "Semantic recall last on policy/env/extension-heavy queries; convert hits to exact rg follow-ups.",
+        intentIds,
+    };
+}
+function routeVerification(intentIds, order) {
+    return {
+        order,
+        id: "verification-source-git-tests",
+        role: "verification",
+        sourceFamily: "source-git-tests",
+        commands: ["git diff -- <path>", "Get-Content <file>"],
+        rationale: "Required proof layer for verified claims.",
+        intentIds,
+    };
+}
+function modalityForIntent(intentIds, structuralIntents) {
+    const structural = structuralIntents ??
+        new Set([
+            "caller-chain",
+            "trap-package-disambiguation",
+            "extension-shared-symbol",
+        ]);
+    const hasStructural = [...intentIds].some((id) => structural.has(id));
+    if (hasStructural) {
+        return [MODALITY_STRUCTURAL, MODALITY_LEXICAL, MODALITY_SEMANTIC];
+    }
+    if (intentIds.has("cross-cutting-discovery") && !intentIds.has("exact-symbol-path")) {
+        return [MODALITY_SEMANTIC, MODALITY_LEXICAL, MODALITY_STRUCTURAL];
+    }
+    return [MODALITY_LEXICAL, MODALITY_STRUCTURAL, MODALITY_SEMANTIC];
+}
+function tokenEconomyForRoute(routeId, platform) {
+    const highEconomyRoutes = new Set([
+        "caller-chain-ast",
+        "trap-demote-codegraph",
+        "extension-codegraph",
+        "ast-codegraph",
+        "platform-semantic",
+    ]);
+    if (highEconomyRoutes.has(routeId)) {
+        return TOKEN_ECONOMY_HIGH;
+    }
+    const lowEconomyRoutes = new Set(["exact-rg-primary"]);
+    if (lowEconomyRoutes.has(routeId) && platform !== PLATFORM_CURSOR) {
+        return TOKEN_ECONOMY_LOW;
+    }
+    return TOKEN_ECONOMY_MEDIUM;
+}
+function largeProject(projectFileCount) {
+    if (projectFileCount === null)
+        return false;
+    return projectFileCount > 2000;
+}
+function orderedRoutesForIntents(intents, includeOptionalAdapters, platform = PLATFORM_GENERIC, projectFileCount = null) {
+    const ids = new Set(intents.map((item) => item.id));
+    const preserve = ids.has("protocol-platform-preserve");
+    const policy = ids.has("policy-document");
+    const caller = ids.has("caller-chain");
+    const trap = ids.has("trap-package-disambiguation");
+    const extension = ids.has("extension-shared-symbol");
+    const env = ids.has("env-config-literal");
+    const exact = ids.has("exact-symbol-path");
+    const conceptual = ids.has("cross-cutting-discovery");
+    const activeIntentIds = [...ids];
+    const isCursor = platform === PLATFORM_CURSOR;
+    const isLarge = largeProject(projectFileCount);
+    let semanticPromoted = false;
+    const routes = [];
+    function append(route) {
+        routes.push({
+            ...route,
+            order: routes.length + 1,
+            intentIds: activeIntentIds,
+            tokenEconomy: tokenEconomyForRoute(route.id, platform),
+            platformNative: route.platformNative ?? false,
+        });
+    }
+    // ── Structural-first intents: caller, trap, extension ──
+    if (caller) {
+        append({
+            id: "caller-chain-ast",
+            role: "ast",
+            sourceFamily: "codegraph",
+            commands: ["codegraph callers <symbol> --path <path> --json"],
+            rationale: "Caller-chain intent: codegraph for precise call edges first.",
+        });
+        append({
+            id: "caller-rg-followup",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <symbol> --glob '*.ts'"],
+            rationale: "Caller-chain intent: rg follow-up for dynamic callsites codegraph may miss.",
+        });
+    }
+    if (trap && !preserve) {
+        append({
+            id: "trap-demote-codegraph",
+            role: "ast",
+            sourceFamily: "codegraph",
+            commands: ["codegraph search <symbol> --path <path> --json"],
+            rationale: "Trap intent: codegraph distinguishes same-named symbols across packages.",
+        });
+        append({
+            id: "trap-demote-rg",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <symbol> packages/<name>/", "rg <symbol> src/"],
+            rationale: "Trap intent: rg follow-up across package boundaries.",
+        });
+    }
+    if (extension && !preserve) {
+        append({
+            id: "extension-codegraph",
+            role: "ast",
+            sourceFamily: "codegraph",
+            commands: ["codegraph search <symbol> --path <path> --json"],
+            rationale: "Extension intent: codegraph finds cross-extension symbol definitions.",
+        });
+        append({
+            id: "extension-rg",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <symbol> extensions/"],
+            rationale: "Extension intent: rg follow-up for extension directory.",
+        });
+    }
+    // ── Lexical-first intents: exact, policy, preserve, env ──
+    const exactPrimaryFirst = preserve || exact;
+    const conceptualPrimary = conceptual && !preserve && !exactPrimaryFirst;
+    if (conceptualPrimary) {
+        if (policy) {
+            append({
+                id: "policy-docs-rg",
+                role: "exact",
+                sourceFamily: "policy-docs",
+                commands: [
+                    'rg -i "storage default|sidecar|sqlite only" AGENTS.md "**/AGENTS.md" README.md CONTRIBUTING.md .trellis/spec',
+                ],
+                rationale: "Policy/document intent: search instruction and spec docs first.",
+            });
+        }
+        const semanticRationale = policy
+            ? "Policy plus conceptual intent: semantic recall after policy docs, before exact rg follow-up."
+            : "Conceptual query without exact signals; semantic recall before exact rg narrowing.";
+        if (isCursor) {
+            append({
+                id: "platform-semantic",
+                role: "semantic",
+                sourceFamily: "platform-semantic",
+                commands: ["cursor @codebase or built-in semantic search"],
+                rationale: semanticRationale + " (platform-native on Cursor)",
+                platformNative: true,
+            });
+        }
+        else {
+            append({
+                id: "semantic-fast-context",
+                role: "semantic",
+                sourceFamily: "fast-context",
+                commands: ["fast_context_search query=<question> project_path=<root>"],
+                rationale: semanticRationale,
+            });
+        }
+        semanticPromoted = true;
+        append({
+            id: "exact-rg-primary",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <pattern> <path>"],
+            rationale: "Exact rg follow-up after semantic recall (or policy docs) narrows candidate files and symbols.",
+        });
+    }
+    else if (policy && !preserve && !exactPrimaryFirst) {
+        append({
+            id: "policy-docs-rg",
+            role: "exact",
+            sourceFamily: "policy-docs",
+            commands: [
+                'rg -i "storage default|sidecar|sqlite only" AGENTS.md "**/AGENTS.md" README.md CONTRIBUTING.md .trellis/spec',
+            ],
+            rationale: "Policy/document intent: search instruction and spec docs first.",
+        });
+        append({
+            id: "exact-rg-primary",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <pattern> <path>"],
+            rationale: "Exact rg after policy doc pass when no symbol/path intent is present.",
+        });
+    }
+    else if (exactPrimaryFirst) {
+        append({
+            id: "exact-rg-primary",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <pattern> <path>"],
+            rationale: "Exact identifiers and paths stay primary.",
+        });
+        if (policy && !preserve) {
+            append({
+                id: "policy-docs-rg",
+                role: "exact",
+                sourceFamily: "policy-docs",
+                commands: [
+                    'rg -i "storage default|sidecar|sqlite only" AGENTS.md "**/AGENTS.md" README.md CONTRIBUTING.md .trellis/spec',
+                ],
+                rationale: "Policy/document branch after exact-primary when both intents match.",
+            });
+        }
+    }
+    if (env && !preserve) {
+        append({
+            id: "env-scripts-rg",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <env-prefix> scripts test e2e bench"],
+            rationale: "Env/config literals: scripts and test trees before src/ modules.",
+        });
+    }
+    if (!routes.some((r) => r.id === "exact-rg-primary")) {
+        append({
+            id: "exact-rg-primary",
+            role: "exact",
+            sourceFamily: "rg",
+            commands: ["rg <pattern> <path>"],
+            rationale: "Baseline exact search.",
+        });
+    }
+    // ── Optional adapters ──
+    if (includeOptionalAdapters) {
+        if (!routes.some((r) => r.id === "caller-chain-ast")) {
+            const cgRationale = isLarge
+                ? "Structural search first on large codebase for token efficiency."
+                : "Structural expansion after exact candidates.";
+            append({
+                id: "ast-codegraph",
+                role: "ast",
+                sourceFamily: "codegraph",
+                commands: [
+                    "codegraph query <symbol-or-search> --path <path> --json",
+                    "codegraph callers <symbol> --path <path> --json",
+                ],
+                rationale: cgRationale,
+            });
+        }
+        if (isCursor) {
+            append({
+                id: "lsp-navigation",
+                role: "lsp",
+                sourceFamily: "language-server",
+                commands: ["definition", "references", "hover"],
+                rationale: "LSP via platform-native Cursor features.",
+                platformNative: true,
+            });
+        }
+        else {
+            append({
+                id: "lsp-navigation",
+                role: "lsp",
+                sourceFamily: "language-server",
+                commands: ["definition", "references", "hover"],
+                rationale: "LSP after candidate symbols exist.",
+            });
+        }
+        if (!semanticPromoted) {
+            if (isCursor) {
+                append({
+                    id: "platform-semantic",
+                    role: "semantic",
+                    sourceFamily: "platform-semantic",
+                    commands: ["cursor @codebase or built-in semantic search"],
+                    rationale: "Semantic recall via platform-native Cursor search.",
+                    platformNative: true,
+                });
+            }
+            else {
+                append({
+                    id: "semantic-fast-context",
+                    role: "semantic",
+                    sourceFamily: "fast-context",
+                    commands: ["fast_context_search query=<question> project_path=<root>"],
+                    rationale: "Semantic recall last; convert to exact rg follow-ups.",
+                });
+            }
+        }
+    }
+    append({
+        id: "verification-source-git-tests",
+        role: "verification",
+        sourceFamily: "source-git-tests",
+        commands: ["git diff -- <path>", "Get-Content <file>"],
+        rationale: "Required proof layer for verified claims.",
+    });
+    // Large project: reorder so structural (ast) routes precede others
+    if (isLarge) {
+        const structural = routes.filter((r) => r.role === "ast");
+        const others = routes.filter((r) => r.role !== "ast");
+        const reordered = [...structural, ...others];
+        return reordered.map((route, index) => ({ ...route, order: index + 1 }));
+    }
+    return routes
+        .sort((a, b) => a.order - b.order)
+        .map((route, index) => ({ ...route, order: index + 1 }));
+}
+function classifyIntents(query) {
+    const intents = [];
+    const preserveHits = matchAny(PRESERVE_SIGNALS, query);
+    if (preserveHits.length > 0) {
+        intents.push(buildIntent("protocol-platform-preserve", "Protocol / platform preserve (F/G)", preserveHits, intentConfidence(preserveHits.length, true), true));
+    }
+    const exactHits = matchAny(EXACT_SYMBOL_SIGNALS, query);
+    if (exactHits.length > 0) {
+        intents.push(buildIntent("exact-symbol-path", "Exact symbol or path", exactHits, intentConfidence(exactHits.length, true), true));
+    }
+    const policyHits = matchAny(POLICY_SIGNALS, query);
+    if (policyHits.length > 0) {
+        intents.push(buildIntent("policy-document", "Policy and document-first (C-class)", policyHits, intentConfidence(policyHits.length, false), false));
+    }
+    const callerHits = matchAny(CALLER_CHAIN_SIGNALS, query);
+    if (callerHits.length > 0) {
+        intents.push(buildIntent("caller-chain", "Caller and assembly chain (B-class)", callerHits, intentConfidence(callerHits.length, false), false));
+    }
+    const trapHits = matchAny(TRAP_SIGNALS, query);
+    if (trapHits.length > 0) {
+        intents.push(buildIntent("trap-package-disambiguation", "Trap demotion and package boundary (E-class)", trapHits, intentConfidence(trapHits.length, false), false));
+    }
+    const extensionHits = matchAny(EXTENSION_SIGNALS, query);
+    if (extensionHits.length > 0) {
+        intents.push(buildIntent("extension-shared-symbol", "Extension shared-symbol disambiguation (A-class)", extensionHits, intentConfidence(extensionHits.length, false), false));
+    }
+    const envHits = matchAny(ENV_LITERAL_SIGNALS, query);
+    if (envHits.length > 0) {
+        intents.push(buildIntent("env-config-literal", "Environment and config literals (D-class)", envHits, intentConfidence(envHits.length, false), false));
+    }
+    if (exactHits.length === 0 && preserveHits.length === 0) {
+        const conceptualHits = matchAny(CONCEPTUAL_SIGNALS, query);
+        if (conceptualHits.length > 0) {
+            intents.push(buildIntent("cross-cutting-discovery", "Conceptual / cross-cutting discovery", conceptualHits, intentConfidence(conceptualHits.length, false), false));
+        }
+    }
+    if (intents.length === 0) {
+        intents.push(buildIntent("exact-symbol-path", "General codebase (exact baseline)", ["default-exact-baseline"], "low", true));
+    }
+    const seen = new Set();
+    return intents.filter((intent) => {
+        if (seen.has(intent.id))
+            return false;
+        seen.add(intent.id);
+        return true;
+    });
+}
+function buildFallbackHints(intents, includeOptionalAdapters, routes, platform = PLATFORM_GENERIC) {
+    const hints = [
+        {
+            when: "rg missing on PATH",
+            action: "Codebase retrieval readiness fails; install or expose rg before claiming readiness.",
+        },
+    ];
+    const isCursor = platform === PLATFORM_CURSOR;
+    if (!includeOptionalAdapters) {
+        hints.push({
+            when: "codebase-retrieval not selected",
+            action: "Skip optional AST/LSP/semantic routes; continue with exact search and verification only.",
+            replacesRole: "semantic",
+        });
+    }
+    if (intents.some((i) => i.id === "policy-document")) {
+        hints.push({
+            when: "semantic Top-1 is implementation-only for policy query",
+            action: "Fall back to policy-doc rg route and AGENTS.md/.trellis/spec reads before accepting semantic ranking.",
+            replacesRole: "semantic",
+        });
+    }
+    const semanticRoute = routes.find((r) => r.role === "semantic");
+    const hasConceptual = intents.some((i) => i.id === "cross-cutting-discovery");
+    const exactPrimary = intents.some((i) => i.id === "exact-symbol-path" && i.preserveExactPrimary);
+    if (includeOptionalAdapters &&
+        semanticRoute &&
+        (hasConceptual || semanticRoute.order >= 3 || exactPrimary)) {
+        if (isCursor) {
+            hints.push({
+                when: "exact rg returns no corroborated file/range candidates (or only trap hits) before final Top-1",
+                action: "Use Cursor @codebase or built-in semantic search per platform-semantic route, then narrow with rg on returned keywords and paths.",
+                replacesRole: "semantic",
+            });
+        }
+        else {
+            hints.push({
+                when: "exact rg returns no corroborated file/range candidates (or only trap hits) before final Top-1",
+                action: "Invoke fast_context_search per semantic-fast-context route, then narrow with rg on returned keywords and paths; semantic output remains recall-only until source reads confirm.",
+                replacesRole: "semantic",
+            });
+        }
+    }
+    return hints;
+}
+function buildWarnings(intents, platform = PLATFORM_GENERIC) {
+    const warnings = [];
+    const low = intents.filter((i) => i.confidence === "low");
+    if (low.length > 0) {
+        warnings.push(`Low-confidence intent classification for: ${low.map((i) => i.id).join(", ")}.`);
+    }
+    const hasPolicy = intents.some((i) => i.id === "policy-document");
+    const hasPreserve = intents.some((i) => i.id === "protocol-platform-preserve");
+    if (hasPolicy && hasPreserve) {
+        warnings.push("Both policy-document and protocol-platform-preserve detected; preserve route keeps exact-symbol primary.");
+    }
+    const hasConceptual = intents.some((i) => i.id === "cross-cutting-discovery");
+    const hasExactIntent = intents.some((i) => i.id === "exact-symbol-path");
+    if (hasConceptual &&
+        !hasExactIntent &&
+        !intents.some((i) => i.id === "protocol-platform-preserve")) {
+        const semanticHint = platform === PLATFORM_CURSOR ? "platform-semantic" : "semantic-fast-context";
+        warnings.push(`Conceptual intent without exact signals; ${semanticHint} route promoted in plan. Convert semantic hits to exact rg follow-ups before final claims.`);
+    }
+    return warnings;
+}
+function verificationForIntents(intents) {
+    if (intents.some((i) => i.id === "policy-document")) {
+        return policyVerification();
+    }
+    if (intents.some((i) => i.id === "caller-chain")) {
+        return callerVerification();
+    }
+    if (intents.some((i) => i.id === "trap-package-disambiguation")) {
+        return trapVerification();
+    }
+    if (intents.some((i) => i.id === "extension-shared-symbol")) {
+        return extensionVerification();
+    }
+    return baseVerification();
+}
+/**
+ * Build a deterministic retrieval plan envelope for a natural-language query.
+ */
+export function routeCodebaseRetrieval(input) {
+    const query = normalizeQuery(input.query);
+    const includeOptionalAdapters = input.codebaseRetrievalSelected !== false;
+    const platform = input.platform && KNOWN_PLATFORMS.has(input.platform)
+        ? input.platform
+        : PLATFORM_GENERIC;
+    const projectFileCount = input.projectFileCount ?? null;
+    if (!query) {
+        const emptyIntent = buildIntent("exact-symbol-path", "General codebase (exact baseline)", ["empty-query"], "low", true);
+        const emptyRoutes = orderedRoutesForIntents([emptyIntent], includeOptionalAdapters, platform, projectFileCount);
+        return {
+            version: CODEBASE_RETRIEVAL_ROUTER_VERSION,
+            query,
+            intents: [emptyIntent],
+            routes: emptyRoutes,
+            adapterState: [],
+            freshness: [],
+            fallback: buildFallbackHints([emptyIntent], includeOptionalAdapters, emptyRoutes, platform),
+            warnings: ["Empty query; only baseline exact route is emitted."],
+            verification: baseVerification(),
+            platform,
+            projectFileCount,
+        };
+    }
+    const intents = classifyIntents(query);
+    const routes = orderedRoutesForIntents(intents, includeOptionalAdapters, platform, projectFileCount);
+    return {
+        version: CODEBASE_RETRIEVAL_ROUTER_VERSION,
+        query,
+        intents,
+        routes,
+        adapterState: [],
+        freshness: [],
+        fallback: buildFallbackHints(intents, includeOptionalAdapters, routes, platform),
+        warnings: buildWarnings(intents, platform),
+        verification: verificationForIntents(intents),
+        platform,
+        projectFileCount,
+    };
+}
+//# sourceMappingURL=codebase-retrieval-router.js.map