@blxzer/cursor-trellis 0.1.0

package/dist/utils/retrieval-execution-telemetry.d.ts

@@ -0,0 +1,162 @@
+import type { CodebaseRetrievalPlanEnvelope } from "./codebase-retrieval-router.js";
+export declare const RG_CORROB_STATUSES: readonly ["not_run", "none", "trap_only", "partial", "sufficient", "unknown"];
+export type RgCorrobStatus = (typeof RG_CORROB_STATUSES)[number];
+export declare const SEMANTIC_SKIP_REASONS: readonly ["rg_corrob_sufficient", "rg_empty_semantic_required", "trap_only_semantic_required", "not_in_plan", "not_applicable", "adapter_unavailable", "agent_stopped_early", "unknown", "manual_not_recorded"];
+export type SemanticSkipReason = (typeof SEMANTIC_SKIP_REASONS)[number];
+export declare const SEMANTIC_OUTCOMES: readonly ["success", "partial", "resource_exhausted", "timeout", "not_configured", "unavailable", "not_run", "unknown"];
+export type SemanticOutcome = (typeof SEMANTIC_OUTCOMES)[number];
+export interface RetrievalAdapterError {
+    adapter: "fast-context" | string;
+    outcome: Exclude<SemanticOutcome, "success" | "not_run">;
+    category: "resource_exhausted" | "timeout" | "not_configured" | "unavailable" | "partial" | "unknown";
+    message?: string;
+    retryable: boolean;
+    fallback: Array<"exact-rg" | "codegraph" | "source-read" | string>;
+}
+export interface RetrievalQueryTelemetry {
+    query_id: string;
+    dataset: "main-50" | "semantic-slice" | string;
+    query_text: string;
+    run_id: string;
+    semantic_in_plan: boolean;
+    semantic_order: number | null;
+    fallback_hint_present: boolean;
+    intents: string[];
+    routes: string[];
+    tools_called: string[];
+    semantic_attempted: boolean;
+    semantic_executed: boolean;
+    semantic_outcome: SemanticOutcome;
+    semantic_success: boolean;
+    semantic_skip_reason: SemanticSkipReason | null;
+    rg_candidate_count: number | null;
+    rg_corrob_status: RgCorrobStatus;
+    trap_only: boolean;
+    corroborated_files: string[];
+    adapter_errors: RetrievalAdapterError[];
+    /** Recall of expected files in the expanded candidate pool (before Top-K compression). */
+    candidate_pool_recall: number | null;
+    /** Recall of expected files in the final Top-K output. */
+    final_top_k_recall: number | null;
+}
+export declare const RETRIEVAL_TELEMETRY_FIELD_OWNERSHIP: {
+    readonly router_plan: readonly ["semantic_in_plan", "semantic_order", "fallback_hint_present", "intents", "routes"];
+    readonly execution_harness: readonly ["tools_called", "semantic_attempted", "semantic_executed", "semantic_outcome", "semantic_success", "semantic_skip_reason", "rg_candidate_count", "rg_corrob_status", "trap_only", "corroborated_files", "adapter_errors", "candidate_pool_recall", "final_top_k_recall"];
+    readonly identity: readonly ["query_id", "dataset", "query_text", "run_id"];
+};
+export interface RetrievalTelemetryMetrics {
+    total_queries: number;
+    semantic_plan_count: number;
+    semantic_exec_count: number;
+    semantic_attempt_count: number;
+    semantic_exec_success_count: number;
+    semantic_plan_rate: number;
+    semantic_exec_rate: number;
+    semantic_attempt_rate: number;
+    semantic_exec_success_rate: number;
+    semantic_outcome_counts: Record<SemanticOutcome, number>;
+    semantic_skip_reason_counts: Record<SemanticSkipReason, number>;
+    avg_candidate_pool_recall: number;
+    avg_final_top_k_recall: number;
+    recall_drop_rate: number;
+}
+export declare function deriveRetrievalTelemetryMetrics(records: readonly RetrievalQueryTelemetry[]): RetrievalTelemetryMetrics;
+export declare const RETRIEVAL_TELEMETRY_EXAMPLES: {
+    main50RgSufficientSkip: {
+        query_id: string;
+        dataset: string;
+        query_text: string;
+        run_id: string;
+        semantic_in_plan: true;
+        semantic_order: number;
+        fallback_hint_present: true;
+        intents: string[];
+        routes: string[];
+        tools_called: string[];
+        semantic_attempted: false;
+        semantic_executed: false;
+        semantic_outcome: "not_run";
+        semantic_success: false;
+        semantic_skip_reason: "rg_corrob_sufficient";
+        rg_candidate_count: number;
+        rg_corrob_status: "sufficient";
+        trap_only: false;
+        corroborated_files: string[];
+        adapter_errors: never[];
+        candidate_pool_recall: null;
+        final_top_k_recall: null;
+    };
+    semanticSliceExecutedSuccess: {
+        query_id: string;
+        dataset: string;
+        query_text: string;
+        run_id: string;
+        semantic_in_plan: true;
+        semantic_order: number;
+        fallback_hint_present: true;
+        intents: string[];
+        routes: string[];
+        tools_called: string[];
+        semantic_attempted: true;
+        semantic_executed: true;
+        semantic_outcome: "success";
+        semantic_success: true;
+        semantic_skip_reason: null;
+        rg_candidate_count: number;
+        rg_corrob_status: "none";
+        trap_only: false;
+        corroborated_files: string[];
+        adapter_errors: never[];
+        candidate_pool_recall: null;
+        final_top_k_recall: null;
+    };
+    semanticSliceResourceExhausted: {
+        query_id: string;
+        dataset: string;
+        query_text: string;
+        run_id: string;
+        semantic_in_plan: true;
+        semantic_order: number;
+        fallback_hint_present: true;
+        intents: string[];
+        routes: string[];
+        tools_called: string[];
+        semantic_attempted: true;
+        semantic_executed: true;
+        semantic_outcome: "resource_exhausted";
+        semantic_success: false;
+        semantic_skip_reason: null;
+        rg_candidate_count: number;
+        rg_corrob_status: "none";
+        trap_only: false;
+        corroborated_files: never[];
+        adapter_errors: {
+            adapter: string;
+            outcome: "resource_exhausted";
+            category: "resource_exhausted";
+            message: string;
+            retryable: false;
+            fallback: string[];
+        }[];
+        candidate_pool_recall: null;
+        final_top_k_recall: null;
+    };
+};
+export type SimulatedRgStatus = "rg_empty" | "trap_only" | "corroborated_exact_sufficient";
+export interface SimulatedRgResult {
+    status: SimulatedRgStatus;
+    candidateCount?: number;
+    files?: string[];
+}
+export type O2ComplianceNextAction = "invoke_semantic" | "continue_exact" | "verify_sources" | "stop_with_skip_reason";
+export interface O2ComplianceDecision {
+    next_action: O2ComplianceNextAction;
+    rationale: string;
+    telemetry: Pick<RetrievalQueryTelemetry, "semantic_in_plan" | "fallback_hint_present" | "rg_candidate_count" | "rg_corrob_status" | "trap_only" | "corroborated_files" | "semantic_skip_reason">;
+}
+/**
+ * Lightweight RB-004 harness: the router cannot know live rg results, so this
+ * function checks execution-layer behavior after a simulated rg pass.
+ */
+export declare function evaluateO2SemanticFallback(plan: Pick<CodebaseRetrievalPlanEnvelope, "routes" | "fallback">, result: SimulatedRgResult): O2ComplianceDecision;
+//# sourceMappingURL=retrieval-execution-telemetry.d.ts.map

package/dist/utils/retrieval-execution-telemetry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-execution-telemetry.d.ts","sourceRoot":"","sources":["../../src/utils/retrieval-execution-telemetry.ts"],"names":[],"mappings":"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"}

package/dist/utils/retrieval-execution-telemetry.js

@@ -0,0 +1,288 @@
+export const RG_CORROB_STATUSES = [
+    "not_run",
+    "none",
+    "trap_only",
+    "partial",
+    "sufficient",
+    "unknown",
+];
+export const SEMANTIC_SKIP_REASONS = [
+    "rg_corrob_sufficient",
+    "rg_empty_semantic_required",
+    "trap_only_semantic_required",
+    "not_in_plan",
+    "not_applicable",
+    "adapter_unavailable",
+    "agent_stopped_early",
+    "unknown",
+    "manual_not_recorded",
+];
+export const SEMANTIC_OUTCOMES = [
+    "success",
+    "partial",
+    "resource_exhausted",
+    "timeout",
+    "not_configured",
+    "unavailable",
+    "not_run",
+    "unknown",
+];
+export const RETRIEVAL_TELEMETRY_FIELD_OWNERSHIP = {
+    router_plan: [
+        "semantic_in_plan",
+        "semantic_order",
+        "fallback_hint_present",
+        "intents",
+        "routes",
+    ],
+    execution_harness: [
+        "tools_called",
+        "semantic_attempted",
+        "semantic_executed",
+        "semantic_outcome",
+        "semantic_success",
+        "semantic_skip_reason",
+        "rg_candidate_count",
+        "rg_corrob_status",
+        "trap_only",
+        "corroborated_files",
+        "adapter_errors",
+        "candidate_pool_recall",
+        "final_top_k_recall",
+    ],
+    identity: ["query_id", "dataset", "query_text", "run_id"],
+};
+function emptyOutcomeCounts() {
+    return Object.fromEntries(SEMANTIC_OUTCOMES.map((value) => [value, 0]));
+}
+function emptySkipReasonCounts() {
+    return Object.fromEntries(SEMANTIC_SKIP_REASONS.map((value) => [value, 0]));
+}
+export function deriveRetrievalTelemetryMetrics(records) {
+    const total = records.length;
+    const outcomeCounts = emptyOutcomeCounts();
+    const skipReasonCounts = emptySkipReasonCounts();
+    let semanticPlanCount = 0;
+    let semanticExecCount = 0;
+    let semanticAttemptCount = 0;
+    let semanticExecSuccessCount = 0;
+    const candidatePoolRecalls = [];
+    const finalTopKRecalls = [];
+    for (const record of records) {
+        if (record.semantic_in_plan)
+            semanticPlanCount += 1;
+        if (record.semantic_executed)
+            semanticExecCount += 1;
+        if (record.semantic_attempted)
+            semanticAttemptCount += 1;
+        if (record.semantic_success && record.semantic_outcome === "success") {
+            semanticExecSuccessCount += 1;
+        }
+        outcomeCounts[record.semantic_outcome] += 1;
+        if (record.semantic_skip_reason) {
+            skipReasonCounts[record.semantic_skip_reason] += 1;
+        }
+        if (record.candidate_pool_recall !== null) {
+            candidatePoolRecalls.push(record.candidate_pool_recall);
+        }
+        if (record.final_top_k_recall !== null) {
+            finalTopKRecalls.push(record.final_top_k_recall);
+        }
+    }
+    const rate = (count) => (total === 0 ? 0 : count / total);
+    const avg = (values) => (values.length === 0 ? 0 : values.reduce((a, b) => a + b, 0) / values.length);
+    const avgCandidatePoolRecall = avg(candidatePoolRecalls);
+    const avgFinalTopKRecall = avg(finalTopKRecalls);
+    const recallDropRate = avgCandidatePoolRecall > 0 ? 1 - avgFinalTopKRecall / avgCandidatePoolRecall : 0;
+    return {
+        total_queries: total,
+        semantic_plan_count: semanticPlanCount,
+        semantic_exec_count: semanticExecCount,
+        semantic_attempt_count: semanticAttemptCount,
+        semantic_exec_success_count: semanticExecSuccessCount,
+        semantic_plan_rate: rate(semanticPlanCount),
+        semantic_exec_rate: rate(semanticExecCount),
+        semantic_attempt_rate: rate(semanticAttemptCount),
+        semantic_exec_success_rate: rate(semanticExecSuccessCount),
+        semantic_outcome_counts: outcomeCounts,
+        semantic_skip_reason_counts: skipReasonCounts,
+        avg_candidate_pool_recall: avgCandidatePoolRecall,
+        avg_final_top_k_recall: avgFinalTopKRecall,
+        recall_drop_rate: recallDropRate,
+    };
+}
+export const RETRIEVAL_TELEMETRY_EXAMPLES = {
+    main50RgSufficientSkip: {
+        query_id: "Q01",
+        dataset: "main-50",
+        query_text: "who calls routeCodebaseRetrieval after exact rg finds source",
+        run_id: "example-main-50",
+        semantic_in_plan: true,
+        semantic_order: 4,
+        fallback_hint_present: true,
+        intents: ["exact-symbol-path", "caller-chain"],
+        routes: ["exact-rg-primary", "caller-chain-ast", "semantic-fast-context"],
+        tools_called: ["rg", "ReadFile"],
+        semantic_attempted: false,
+        semantic_executed: false,
+        semantic_outcome: "not_run",
+        semantic_success: false,
+        semantic_skip_reason: "rg_corrob_sufficient",
+        rg_candidate_count: 3,
+        rg_corrob_status: "sufficient",
+        trap_only: false,
+        corroborated_files: ["packages/cli/src/utils/codebase-retrieval-router.ts"],
+        adapter_errors: [],
+        candidate_pool_recall: null,
+        final_top_k_recall: null,
+    },
+    semanticSliceExecutedSuccess: {
+        query_id: "S04",
+        dataset: "semantic-slice",
+        query_text: "how does retrieval policy work across modules",
+        run_id: "example-semantic-slice",
+        semantic_in_plan: true,
+        semantic_order: 1,
+        fallback_hint_present: true,
+        intents: ["cross-cutting-discovery"],
+        routes: ["semantic-fast-context", "exact-rg-primary"],
+        tools_called: ["rg", "fast_context_search", "rg", "ReadFile"],
+        semantic_attempted: true,
+        semantic_executed: true,
+        semantic_outcome: "success",
+        semantic_success: true,
+        semantic_skip_reason: null,
+        rg_candidate_count: 0,
+        rg_corrob_status: "none",
+        trap_only: false,
+        corroborated_files: [".trellis/spec/guides/retrieval-daily-guide.md"],
+        adapter_errors: [],
+        candidate_pool_recall: null,
+        final_top_k_recall: null,
+    },
+    semanticSliceResourceExhausted: {
+        query_id: "S08",
+        dataset: "semantic-slice",
+        query_text: "conceptual retrieval boundary question with quota failure",
+        run_id: "example-semantic-slice",
+        semantic_in_plan: true,
+        semantic_order: 1,
+        fallback_hint_present: true,
+        intents: ["cross-cutting-discovery"],
+        routes: ["semantic-fast-context", "exact-rg-primary"],
+        tools_called: ["rg", "fast_context_search", "rg", "ReadFile"],
+        semantic_attempted: true,
+        semantic_executed: true,
+        semantic_outcome: "resource_exhausted",
+        semantic_success: false,
+        semantic_skip_reason: null,
+        rg_candidate_count: 0,
+        rg_corrob_status: "none",
+        trap_only: false,
+        corroborated_files: [],
+        adapter_errors: [
+            {
+                adapter: "fast-context",
+                outcome: "resource_exhausted",
+                category: "resource_exhausted",
+                message: "fast-context provider returned resource_exhausted",
+                retryable: false,
+                fallback: ["exact-rg", "codegraph", "source-read"],
+            },
+        ],
+        candidate_pool_recall: null,
+        final_top_k_recall: null,
+    },
+};
+function hasSemanticRoute(plan) {
+    return plan.routes.some((route) => route.role === "semantic" || route.id === "semantic-fast-context");
+}
+function hasSemanticFallbackHint(plan) {
+    return plan.fallback.some((hint) => hint.replacesRole === "semantic" || /fast_context_search|semantic/i.test(hint.action));
+}
+function rgTelemetry(result) {
+    if (result.status === "corroborated_exact_sufficient") {
+        return {
+            rg_candidate_count: result.candidateCount ?? Math.max(result.files?.length ?? 1, 1),
+            rg_corrob_status: "sufficient",
+            trap_only: false,
+            corroborated_files: result.files ?? [],
+        };
+    }
+    if (result.status === "trap_only") {
+        return {
+            rg_candidate_count: result.candidateCount ?? Math.max(result.files?.length ?? 1, 1),
+            rg_corrob_status: "trap_only",
+            trap_only: true,
+            corroborated_files: [],
+        };
+    }
+    return {
+        rg_candidate_count: result.candidateCount ?? 0,
+        rg_corrob_status: "none",
+        trap_only: false,
+        corroborated_files: [],
+    };
+}
+/**
+ * Lightweight RB-004 harness: the router cannot know live rg results, so this
+ * function checks execution-layer behavior after a simulated rg pass.
+ */
+export function evaluateO2SemanticFallback(plan, result) {
+    const semanticInPlan = hasSemanticRoute(plan);
+    const fallbackHintPresent = hasSemanticFallbackHint(plan);
+    const baseTelemetry = {
+        semantic_in_plan: semanticInPlan,
+        fallback_hint_present: fallbackHintPresent,
+        ...rgTelemetry(result),
+    };
+    if (!semanticInPlan) {
+        return {
+            next_action: "continue_exact",
+            rationale: "Semantic route is not present in the router plan.",
+            telemetry: {
+                ...baseTelemetry,
+                semantic_skip_reason: "not_in_plan",
+            },
+        };
+    }
+    if (result.status === "corroborated_exact_sufficient") {
+        return {
+            next_action: "stop_with_skip_reason",
+            rationale: "Corroborated exact evidence is sufficient; semantic is optional.",
+            telemetry: {
+                ...baseTelemetry,
+                semantic_skip_reason: "rg_corrob_sufficient",
+            },
+        };
+    }
+    if (fallbackHintPresent && result.status === "trap_only") {
+        return {
+            next_action: "invoke_semantic",
+            rationale: "Only trap candidates were found; execution must continue to semantic recall or equivalent trap demotion before final claims.",
+            telemetry: {
+                ...baseTelemetry,
+                semantic_skip_reason: null,
+            },
+        };
+    }
+    if (fallbackHintPresent && result.status === "rg_empty") {
+        return {
+            next_action: "invoke_semantic",
+            rationale: "No corroborated file/range candidates were found; O2 fallback requires semantic recall as the next action.",
+            telemetry: {
+                ...baseTelemetry,
+                semantic_skip_reason: null,
+            },
+        };
+    }
+    return {
+        next_action: "verify_sources",
+        rationale: "Exact evidence is incomplete; continue verification before final claims.",
+        telemetry: {
+            ...baseTelemetry,
+            semantic_skip_reason: "unknown",
+        },
+    };
+}
+//# sourceMappingURL=retrieval-execution-telemetry.js.map

package/dist/utils/retrieval-execution-telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-execution-telemetry.js","sourceRoot":"","sources":["../../src/utils/retrieval-execution-telemetry.ts"],"names":[],"mappings":"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"}

package/dist/utils/retrieval-result-ranking.d.ts

@@ -0,0 +1,40 @@
+export type RetrievalRankingIntent = "caller-chain" | "trap-package-disambiguation" | "env-config-literal" | "exact-symbol-path" | "protocol-platform-preserve" | string;
+export interface RetrievalResultCandidate {
+    path: string;
+    baseRank: number;
+    score?: number;
+    matchedIntents?: RetrievalRankingIntent[];
+    evidenceType?: "caller-callsite" | "assembly" | "trap" | "env-script" | "implementation" | "protocol" | "codegraph-symbol" | "codegraph-caller" | "platform-semantic" | string;
+    sourceRole?: string;
+    corroborated?: boolean;
+    expectedHint?: boolean;
+    trapHint?: boolean;
+    exactPreserve?: boolean;
+}
+export interface RankedRetrievalResultCandidate extends RetrievalResultCandidate {
+    adjustedScore: number;
+    rankingReasons: string[];
+}
+export interface RankRetrievalResultOptions {
+    intents: RetrievalRankingIntent[];
+    topK?: number;
+    expandedPoolSize?: number;
+    callerPoolExpansion?: {
+        enabled: boolean;
+        minConcreteCallers: number;
+    };
+}
+export interface RankedRetrievalResult {
+    expandedPoolSize: number;
+    expandedPool: RankedRetrievalResultCandidate[];
+    topCandidates: RankedRetrievalResultCandidate[];
+    warnings: string[];
+}
+export declare function rankRetrievalResultCandidates(candidates: readonly RetrievalResultCandidate[], options: RankRetrievalResultOptions): RankedRetrievalResult;
+export interface PagedCallerResult {
+    callers: RetrievalResultCandidate[];
+    pagesConsumed: number;
+    deduplicatedCount: number;
+}
+export declare function pagedCallerAggregation(initialCallers: readonly RetrievalResultCandidate[], maxPages: number, fetchPage: (page: number) => RetrievalResultCandidate[]): PagedCallerResult;
+//# sourceMappingURL=retrieval-result-ranking.d.ts.map

package/dist/utils/retrieval-result-ranking.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"retrieval-result-ranking.d.ts","sourceRoot":"","sources":["../../src/utils/retrieval-result-ranking.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,sBAAsB,GAC9B,cAAc,GACd,6BAA6B,GAC7B,oBAAoB,GACpB,mBAAmB,GACnB,4BAA4B,GAC5B,MAAM,CAAC;AAEX,MAAM,WAAW,wBAAwB;IACvC,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,MAAM,CAAC;IACjB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,YAAY,CAAC,EACT,iBAAiB,GACjB,UAAU,GACV,MAAM,GACN,YAAY,GACZ,gBAAgB,GAChB,UAAU,GACV,kBAAkB,GAClB,kBAAkB,GAClB,mBAAmB,GACnB,MAAM,CAAC;IACX,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAED,MAAM,WAAW,8BAA+B,SAAQ,wBAAwB;IAC9E,aAAa,EAAE,MAAM,CAAC;IACtB,cAAc,EAAE,MAAM,EAAE,CAAC;CAC1B;AAED,MAAM,WAAW,0BAA0B;IACzC,OAAO,EAAE,sBAAsB,EAAE,CAAC;IAClC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,mBAAmB,CAAC,EAAE;QACpB,OAAO,EAAE,OAAO,CAAC;QACjB,kBAAkB,EAAE,MAAM,CAAC;KAC5B,CAAC;CACH;AAED,MAAM,WAAW,qBAAqB;IACpC,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,8BAA8B,EAAE,CAAC;IAC/C,aAAa,EAAE,8BAA8B,EAAE,CAAC;IAChD,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAgHD,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,SAAS,wBAAwB,EAAE,EAC/C,OAAO,EAAE,0BAA0B,GAClC,qBAAqB,CAiDvB;AAED,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,wBAAwB,EAAE,CAAC;IACpC,aAAa,EAAE,MAAM,CAAC;IACtB,iBAAiB,EAAE,MAAM,CAAC;CAC3B;AAED,wBAAgB,sBAAsB,CACpC,cAAc,EAAE,SAAS,wBAAwB,EAAE,EACnD,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,wBAAwB,EAAE,GACtD,iBAAiB,CAsCnB"}