@octocodeai/octocode-tools-core 16.6.3 → 17.0.2

package/dist/oql/normalize/batch.d.ts

@@ -0,0 +1,2 @@
+import type { OqlBatch, OqlInputBatch } from '../types.js';
+export declare function normalizeBatch(input: OqlInputBatch): OqlBatch;

package/dist/oql/normalize/materialize.d.ts

@@ -0,0 +1,2 @@
+import type { MaterializePolicy, OqlInputQuery, OqlQuery, Predicate, QuerySource } from '../types.js';
+export declare function normalizeMaterialize(raw: OqlInputQuery, from: QuerySource | undefined, where: Predicate | undefined, target: OqlQuery['target']): MaterializePolicy | undefined;

package/dist/oql/normalize/params.d.ts

@@ -0,0 +1,2 @@
+import type { OqlInputQuery, OqlQuery } from '../types.js';
+export declare function normalizeParams(raw: OqlInputQuery, target: OqlQuery['target']): Record<string, unknown> | undefined;

package/dist/oql/normalize/query.d.ts

@@ -0,0 +1,2 @@
+import { type OqlInputQuery, type OqlQuery } from '../types.js';
+export declare function normalizeQuery(input: OqlInputQuery): OqlQuery;

package/dist/oql/normalize/scope.d.ts

@@ -0,0 +1,2 @@
+import type { OqlInputQuery, QueryScope, QuerySource } from '../types.js';
+export declare function normalizeScope(raw: OqlInputQuery, from: QuerySource | undefined): QueryScope | undefined;

package/dist/oql/normalize/shared.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Shared helpers used across the normalize/* submodules: the `fail()`
+ * diagnostic-throw shorthand and zod-error formatting.
+ */
+import { diagnostic } from '../diagnostics.js';
+export declare function fail(...diagnostics: ReturnType<typeof diagnostic>[]): never;
+export declare function formatZodError(error: unknown): string;

package/dist/oql/normalize/source.d.ts

@@ -0,0 +1,2 @@
+import { type OqlInputQuery, type OqlQuery, type QuerySource } from '../types.js';
+export declare function normalizeSource(raw: OqlInputQuery, target: OqlQuery['target']): QuerySource | undefined;

package/dist/oql/normalize/where.d.ts

@@ -0,0 +1,2 @@
+import type { OqlInputQuery, OqlQuery, Predicate } from '../types.js';
+export declare function normalizeWhere(raw: OqlInputQuery, target: OqlQuery['target']): Predicate | undefined;

package/dist/oql/normalize.d.ts

@@ -1,5 +1,20 @@
-import { type OqlCanonicalInput, type OqlInputQuery, type OqlQuery, type OqlSearchInput } from './types.js';
-declare function asArray<T>(v: T | T[] | undefined): T[] | undefined;
+/**
+ * OQL normalizer: raw sugar in, strict canonical OQL out.
+ *
+ * Rules (see OCTOCODE_QUERY_LANGUAGE.md §normalization):
+ *  - sugar is accepted only when it has a deterministic rewrite;
+ *  - ambiguous sugar fails with `ambiguousSugar`;
+ *  - reserved targets fail with `unsupportedTarget`;
+ *  - unknown fields fail with `unknownField`;
+ *  - canonical output contains no shorthand fields.
+ *
+ * Predicate IDs are NOT injected here — the planner derives stable IDs from
+ * node position (or a user-provided `id`) so the canonical `where` stays clean.
+ *
+ * This file is a thin barrel/orchestrator: the actual per-clause
+ * normalization logic lives under ./normalize/* (source, scope, where,
+ * materialize, params, query orchestration, batch handling).
+ */
+import type { OqlCanonicalInput, OqlSearchInput } from './types.js';
+export { normalizeQuery } from './normalize/query.js';
 export declare function normalizeInput(input: OqlSearchInput): OqlCanonicalInput;
-export declare function normalizeQuery(input: OqlInputQuery): OqlQuery;
-export { asArray };

package/dist/oql/planner/planDiagnostics.d.ts

@@ -0,0 +1,13 @@
+import type { MaterializePolicy, OqlDiagnostic, OqlPlanNode, OqlQuery } from '../types.js';
+/**
+ * A `controls.search.sort` value outside the target lane's executable set is
+ * IGNORED by the backend (files: localFindFiles sortBy; code: search ranking).
+ * Warn instead of silently returning default ordering — non-blocking because
+ * ordering never changes WHICH rows exist, only their sequence.
+ */
+export declare function sortApplicabilityDiagnostics(query: OqlQuery): OqlDiagnostic[];
+export declare function adapterValidationDiagnostics(query: OqlQuery, nodes: OqlPlanNode[]): OqlDiagnostic[];
+export declare function decideMaterialization(query: OqlQuery, diagnostics: OqlDiagnostic[]): (MaterializePolicy & {
+    required: boolean;
+    reason: string;
+}) | undefined;

package/dist/oql/planner/predicateRouting.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Predicate-tree walking + transformer routing for the OQL planner.
+ *
+ * Responsible for:
+ *  - walking the predicate tree and routing every leaf/boolean node
+ *    (invariant: pushed + residual + routed + unsupported == all predicate
+ *    nodes);
+ *  - recording backend calls and transformer traces as routing decisions are
+ *    made, including the GitHub materialization fallback for multi-leaf
+ *    booleans and unrouted `files`/`code` targets;
+ *  - picking the transformer registry entry for a given query/source pair.
+ */
+import { type CapabilityContext } from '../capabilities.js';
+import type { TransformerRegistryEntry } from '../transformers/contract.js';
+import type { OqlBackendCall, OqlDiagnostic, OqlExplainPlan, OqlPlanNode, OqlQuery, PlanRoute, Predicate, QuerySource } from '../types.js';
+export interface WalkResult {
+    nodes: OqlPlanNode[];
+    diagnostics: OqlDiagnostic[];
+    backendCalls: OqlBackendCall[];
+    transformers: OqlExplainPlan['transformers'];
+}
+/**
+ * Walk the predicate tree, routing every leaf and recording a node per
+ * predicate (boolean nodes included). Boolean nodes are routed by composing
+ * child routes.
+ */
+export declare function walkPredicate(query: OqlQuery, predicate: Predicate, path: string, ctx: CapabilityContext, out: WalkResult, inNegation?: boolean): PlanRoute;
+export declare function addBackendCall(calls: OqlBackendCall[], call: OqlBackendCall): void;
+export declare function addTransformerTrace(out: WalkResult, transformer: TransformerRegistryEntry | undefined): void;
+export declare function addTransformerBackendCalls(out: WalkResult, transformer: TransformerRegistryEntry | undefined, source?: QuerySource): boolean;
+export declare function addGithubFilesMaterializationCalls(out: WalkResult, source: QuerySource): boolean;
+export declare function addGithubMaterializationCalls(out: WalkResult, source: QuerySource, target: OqlQuery['target'], localTransformer?: TransformerRegistryEntry | undefined): boolean;
+export declare function containsStructuralPredicate(predicate: Predicate | undefined): boolean;
+export declare function localTransformerForRoutedQuery(query: OqlQuery): TransformerRegistryEntry | undefined;
+export declare function transformerForQuery(query: OqlQuery, source: QuerySource): TransformerRegistryEntry | undefined;

package/dist/oql/predicateUtils.d.ts

@@ -0,0 +1,3 @@
+import type { Predicate } from './types.js';
+/** Counts all/any/not nodes plus their leaves — used for the boolean-expansion budget and plan diagnostics. */
+export declare function countPredicateNodes(p: Predicate | undefined): number;

package/dist/oql/research/analyze/manifest-scan.d.ts

@@ -0,0 +1,4 @@
+import { type Manifest, type ResearchDependencyIssue, type SourceFile } from './types.js';
+export declare function walkFiles(root: string, maxFiles: number): Promise<string[]>;
+export declare function readManifests(paths: readonly string[]): Promise<Manifest[]>;
+export declare function collectDependencyIssues(root: string, manifests: readonly Manifest[], sourceFiles: readonly SourceFile[], workspacePackages: ReadonlySet<string>): readonly ResearchDependencyIssue[];

package/dist/oql/research/analyze/source-graph.d.ts

@@ -0,0 +1,7 @@
+import { type GraphFactCapability } from '../../../utils/contextUtils.js';
+import { type Manifest, type ResearchGraphCapabilitySummary, type ResearchGraphFactFile, type SourceFile } from './types.js';
+export declare function readSourceFiles(root: string, files: readonly string[]): Promise<SourceFile[]>;
+export declare function summarizeGraphCapabilities(sourceFiles: readonly SourceFile[], graphFacts: readonly ResearchGraphFactFile[], capabilities: readonly GraphFactCapability[]): ResearchGraphCapabilitySummary;
+export declare function buildFileGraph(sourceFiles: readonly SourceFile[]): ReadonlyMap<string, readonly string[]>;
+export declare function collectEntrypoints(root: string, manifests: readonly Manifest[], sourceFiles: readonly SourceFile[]): readonly string[];
+export declare function reachableFiles(entrypoints: readonly string[], graph: ReadonlyMap<string, readonly string[]>): ReadonlySet<string>;

package/dist/oql/research/analyze/symbol-scoring.d.ts

@@ -0,0 +1,4 @@
+import type { ExportSymbol, ResearchSymbolRow, SourceFile } from './types.js';
+export declare function collectExportSymbols(sourceFiles: readonly SourceFile[]): Promise<ExportSymbol[]>;
+export declare function scoreSymbols(symbols: readonly ExportSymbol[], sourceFiles: readonly SourceFile[], reachable: ReadonlySet<string>): readonly ResearchSymbolRow[];
+export declare function cacheTokens(sourceFiles: readonly SourceFile[]): Promise<void>;

package/dist/oql/research/analyze/types.d.ts

@@ -0,0 +1,163 @@
+export declare const FALLBACK_SOURCE_EXTENSIONS: readonly [".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs", ".mts", ".cts"];
+export declare const MANIFEST_NAME = "package.json";
+export declare const DEFAULT_EXCLUDE_DIRS: Set<string>;
+export declare const NODE_BUILTINS: Set<string>;
+export type ResearchIntent = 'general' | 'reachability' | 'dependencies' | 'symbols';
+export type ResearchMode = 'plan' | 'analyze' | 'prove';
+export type ResearchFlowStep = {
+    readonly id: string;
+    readonly purpose: string;
+    readonly tools: readonly string[];
+    readonly produces: readonly string[];
+    readonly evidence: 'heuristic' | 'proof';
+};
+export type ResearchSymbolVerdict = 'reachable' | 'candidate-unused-export' | 'transitive-dead' | 'unused-export' | 'unknown';
+export type ResearchRetentionSource = 'ast' | 'ripgrep';
+export type ResearchSymbolRow = {
+    readonly symbol: string;
+    readonly kind: string;
+    readonly file: string;
+    readonly line: number;
+    readonly evidenceSource: 'ast' | 'regex';
+    /** How cross-file retention was established. Prefer `ast`; `ripgrep` is lexical fallback only. */
+    readonly retentionSource: ResearchRetentionSource;
+    readonly directRefs: number;
+    readonly externalRefs: number;
+    readonly retainedBy: readonly string[];
+    readonly verdict: ResearchSymbolVerdict;
+};
+export type ResearchGraphFactFile = {
+    readonly file: string;
+    readonly source: 'native-ast';
+    readonly language: string;
+    readonly declarations: readonly {
+        readonly name: string;
+        readonly kind: string;
+        readonly line: number;
+        readonly exported: boolean;
+        readonly parent?: string;
+    }[];
+    readonly imports: readonly {
+        readonly specifier: string;
+        readonly line: number;
+        readonly importKind: string;
+        readonly localName?: string;
+        readonly importedName?: string;
+    }[];
+    readonly exports: readonly {
+        readonly name: string;
+        readonly line: number;
+        readonly exportKind: string;
+        readonly localName?: string;
+        readonly source?: string;
+    }[];
+    readonly calls: readonly {
+        readonly caller: string;
+        readonly callee: string;
+        readonly line: number;
+        readonly kind: string;
+    }[];
+    readonly edges: readonly {
+        readonly from: string;
+        readonly to: string;
+        readonly relation: string;
+        readonly source: string;
+        readonly line: number;
+    }[];
+    readonly diagnostics: readonly string[];
+};
+export type ResearchFileIssue = {
+    readonly kind: 'unusedFile';
+    readonly file: string;
+    readonly retainedBy: readonly string[];
+    readonly verdict: 'unused-file';
+};
+export type ResearchDependencyIssue = {
+    readonly kind: 'unlistedDependency' | 'unusedDependency' | 'duplicateDependency';
+    readonly packageName: string;
+    readonly manifest: string;
+    readonly usedBy: readonly string[];
+    readonly declaredIn: readonly string[];
+    readonly verdict: string;
+};
+export type ResearchManifestSummary = {
+    readonly manifest: string;
+    readonly name?: string;
+    readonly entrypoints: readonly string[];
+    readonly dependencyCount: number;
+};
+export type ResearchGraphCapabilitySummary = {
+    readonly graphFactExtensions: readonly string[];
+    readonly capabilityCount: number;
+    readonly factFamilies: readonly string[];
+    readonly sourceFilesByLanguage: Readonly<Record<string, number>>;
+    readonly graphFilesByLanguage: Readonly<Record<string, number>>;
+    readonly missingGraphFacts: readonly {
+        readonly extension: string;
+        readonly files: number;
+        readonly reason: string;
+    }[];
+};
+export type ResearchAnalysisResult = {
+    readonly kind: 'researchFlow';
+    readonly goal: string;
+    readonly intent: ResearchIntent;
+    readonly facets: readonly string[];
+    readonly mode: ResearchMode;
+    readonly root: string;
+    readonly flow: readonly ResearchFlowStep[];
+    readonly summary: {
+        readonly manifests: number;
+        readonly sourceFiles: number;
+        readonly entrypoints: number;
+        readonly reachableFiles: number;
+        readonly unusedFiles: number;
+        readonly unlistedDependencies: number;
+        readonly unusedDependencies: number;
+        readonly duplicateDependencies: number;
+        readonly exportedSymbols: number;
+        readonly candidateUnusedExports: number;
+        readonly transitiveDeadExports: number;
+        readonly nativeGraphFiles: number;
+        readonly nativeGraphDeclarations: number;
+        readonly nativeGraphCalls: number;
+    };
+    readonly manifests: readonly ResearchManifestSummary[];
+    readonly files: readonly ResearchFileIssue[];
+    readonly dependencies: readonly ResearchDependencyIssue[];
+    readonly symbols: readonly ResearchSymbolRow[];
+    readonly graphFacts: readonly ResearchGraphFactFile[];
+    readonly graphCapabilities: ResearchGraphCapabilitySummary;
+    readonly caveats: readonly string[];
+};
+export type AnalyzeResearchOptions = {
+    readonly root: string;
+    readonly goal?: string;
+    readonly intent?: string;
+    readonly facets?: readonly string[];
+    readonly mode?: ResearchMode;
+    readonly maxFiles?: number;
+};
+export type Manifest = {
+    readonly path: string;
+    readonly dir: string;
+    readonly name?: string;
+    readonly deps: ReadonlyMap<string, readonly string[]>;
+    readonly entrypoints: readonly string[];
+};
+export type SourceFile = {
+    readonly path: string;
+    readonly rel: string;
+    readonly extension: string;
+    readonly language: string;
+    readonly imports: readonly string[];
+    readonly externalPackages: readonly string[];
+    readonly graphFacts?: ResearchGraphFactFile;
+};
+export type ExportSymbol = {
+    readonly symbol: string;
+    readonly kind: string;
+    readonly file: string;
+    readonly line: number;
+    readonly evidenceSource: 'ast' | 'regex';
+};

package/dist/oql/research/analyze/utils.d.ts

@@ -0,0 +1,16 @@
+import { type GraphFactCapability } from '../../../utils/contextUtils.js';
+export declare function sourceExtensions(): ReadonlySet<string>;
+export declare function graphFactCapabilities(): readonly GraphFactCapability[];
+export declare function countBy<T>(items: readonly T[], key: (item: T) => string): Readonly<Record<string, number>>;
+export declare function resolveImport(dir: string, specifier: string, known: ReadonlySet<string>): string | undefined;
+export declare function resolveExistingPath(base: string, known: ReadonlySet<string>): string | undefined;
+export declare function isRelativeSpecifier(specifier: string): boolean;
+export declare function packageNameFromSpecifier(specifier: string): string | undefined;
+export declare function recordValue(value: unknown): Record<string, unknown> | undefined;
+export declare function stringValue(value: unknown): string | undefined;
+export declare function isNonEmptyString(value: string | undefined): value is string;
+export declare function isString(value: unknown): value is string;
+export declare function uniqueStrings(values: readonly string[]): readonly string[];
+export declare function relative(root: string, file: string): string;
+export declare function exportKind(line: string): string;
+export declare function calleeRefersToSymbol(callee: string, symbol: string): boolean;

package/dist/oql/research/analyze.d.ts

@@ -1,134 +1,3 @@
-export type ResearchIntent = 'general' | 'reachability' | 'dependencies' | 'symbols';
-export type ResearchMode = 'plan' | 'analyze' | 'prove';
-export type ResearchFlowStep = {
-    readonly id: string;
-    readonly purpose: string;
-    readonly tools: readonly string[];
-    readonly produces: readonly string[];
-    readonly evidence: 'heuristic' | 'proof';
-};
-export type ResearchSymbolVerdict = 'reachable' | 'candidate-unused-export' | 'transitive-dead' | 'unused-export' | 'unknown';
-export type ResearchSymbolRow = {
-    readonly symbol: string;
-    readonly kind: string;
-    readonly file: string;
-    readonly line: number;
-    readonly evidenceSource: 'ast' | 'regex';
-    readonly directRefs: number;
-    readonly externalRefs: number;
-    readonly retainedBy: readonly string[];
-    readonly verdict: ResearchSymbolVerdict;
-};
-export type ResearchGraphFactFile = {
-    readonly file: string;
-    readonly source: 'native-ast';
-    readonly language: string;
-    readonly declarations: readonly {
-        readonly name: string;
-        readonly kind: string;
-        readonly line: number;
-        readonly exported: boolean;
-        readonly parent?: string;
-    }[];
-    readonly imports: readonly {
-        readonly specifier: string;
-        readonly line: number;
-        readonly importKind: string;
-        readonly localName?: string;
-        readonly importedName?: string;
-    }[];
-    readonly exports: readonly {
-        readonly name: string;
-        readonly line: number;
-        readonly exportKind: string;
-        readonly localName?: string;
-        readonly source?: string;
-    }[];
-    readonly calls: readonly {
-        readonly caller: string;
-        readonly callee: string;
-        readonly line: number;
-        readonly kind: string;
-    }[];
-    readonly edges: readonly {
-        readonly from: string;
-        readonly to: string;
-        readonly relation: string;
-        readonly source: string;
-        readonly line: number;
-    }[];
-    readonly diagnostics: readonly string[];
-};
-export type ResearchFileIssue = {
-    readonly kind: 'unusedFile';
-    readonly file: string;
-    readonly retainedBy: readonly string[];
-    readonly verdict: 'unused-file';
-};
-export type ResearchDependencyIssue = {
-    readonly kind: 'unlistedDependency' | 'unusedDependency' | 'duplicateDependency';
-    readonly packageName: string;
-    readonly manifest: string;
-    readonly usedBy: readonly string[];
-    readonly declaredIn: readonly string[];
-    readonly verdict: string;
-};
-export type ResearchManifestSummary = {
-    readonly manifest: string;
-    readonly name?: string;
-    readonly entrypoints: readonly string[];
-    readonly dependencyCount: number;
-};
-export type ResearchGraphCapabilitySummary = {
-    readonly graphFactExtensions: readonly string[];
-    readonly capabilityCount: number;
-    readonly factFamilies: readonly string[];
-    readonly sourceFilesByLanguage: Readonly<Record<string, number>>;
-    readonly graphFilesByLanguage: Readonly<Record<string, number>>;
-    readonly missingGraphFacts: readonly {
-        readonly extension: string;
-        readonly files: number;
-        readonly reason: string;
-    }[];
-};
-export type ResearchAnalysisResult = {
-    readonly kind: 'researchFlow';
-    readonly goal: string;
-    readonly intent: ResearchIntent;
-    readonly facets: readonly string[];
-    readonly mode: ResearchMode;
-    readonly root: string;
-    readonly flow: readonly ResearchFlowStep[];
-    readonly summary: {
-        readonly manifests: number;
-        readonly sourceFiles: number;
-        readonly entrypoints: number;
-        readonly reachableFiles: number;
-        readonly unusedFiles: number;
-        readonly unlistedDependencies: number;
-        readonly unusedDependencies: number;
-        readonly duplicateDependencies: number;
-        readonly exportedSymbols: number;
-        readonly candidateUnusedExports: number;
-        readonly transitiveDeadExports: number;
-        readonly nativeGraphFiles: number;
-        readonly nativeGraphDeclarations: number;
-        readonly nativeGraphCalls: number;
-    };
-    readonly manifests: readonly ResearchManifestSummary[];
-    readonly files: readonly ResearchFileIssue[];
-    readonly dependencies: readonly ResearchDependencyIssue[];
-    readonly symbols: readonly ResearchSymbolRow[];
-    readonly graphFacts: readonly ResearchGraphFactFile[];
-    readonly graphCapabilities: ResearchGraphCapabilitySummary;
-    readonly caveats: readonly string[];
-};
-export type AnalyzeResearchOptions = {
-    readonly root: string;
-    readonly goal?: string;
-    readonly intent?: string;
-    readonly facets?: readonly string[];
-    readonly mode?: ResearchMode;
-    readonly maxFiles?: number;
-};
+import type { AnalyzeResearchOptions, ResearchAnalysisResult } from './analyze/types.js';
+export type { AnalyzeResearchOptions, ResearchAnalysisResult, ResearchDependencyIssue, ResearchFileIssue, ResearchFlowStep, ResearchGraphCapabilitySummary, ResearchGraphFactFile, ResearchIntent, ResearchManifestSummary, ResearchMode, ResearchRetentionSource, ResearchSymbolRow, ResearchSymbolVerdict, } from './analyze/types.js';
 export declare function analyzeResearchFlow(options: AnalyzeResearchOptions): Promise<ResearchAnalysisResult>;

package/dist/oql/research/packets/builders.d.ts

@@ -0,0 +1,4 @@
+import type { ResearchAnalysisResult } from '../analyze.js';
+import type { ResearchEvidencePacket, ResearchGraphSummary, ResearchPacketBundle } from './types.js';
+export declare function tallyPacketVerdicts(packets: readonly ResearchEvidencePacket[]): Pick<ResearchGraphSummary, 'byVerdict' | 'facts' | 'edges'>;
+export declare function buildResearchPackets(analysis: ResearchAnalysisResult): ResearchPacketBundle;

package/dist/oql/research/packets/types.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Evidence model for research packets.
+ *
+ * Pure type/interface definitions describing the evidence graph — subjects,
+ * facts, edges, verdicts, and the `ResearchEvidencePacket` shape itself. No
+ * construction logic here; see `./builders.ts` for how `ResearchAnalysisResult`
+ * is turned into packets built from these types.
+ *
+ * HONESTY CONTRACT: this layer never invents proof. Native AST facts can prove
+ * syntax-level declarations/imports/exports, but cross-file references remain
+ * heuristic until LSP proof is attached by the graph adapter or followed via
+ * `next.semantic`.
+ */
+import type { OqlContinuation } from '../../types.js';
+export type EvidenceSource = 'ripgrep' | 'regex' | 'ast' | 'symbols' | 'lsp' | 'manifest' | 'graph' | 'exactRead';
+export type EvidenceConfidence = 'exact' | 'heuristic' | 'partial';
+export interface EvidenceLocation {
+    uri: string;
+    range?: {
+        start: {
+            line: number;
+            character?: number;
+        };
+        end?: {
+            line: number;
+            character?: number;
+        };
+    };
+}
+export interface EvidenceSubject extends EvidenceLocation {
+    id: string;
+    kind: 'file' | 'symbol' | 'function' | 'class' | 'method' | 'interface' | 'type' | 'dependency' | 'package' | 'entrypoint';
+    name?: string;
+    symbolKind?: number | string;
+    language?: string;
+}
+export type EvidenceClaim = 'defines' | 'declares' | 'exports' | 'imports' | 'references' | 'calls' | 'extends' | 'implements' | 'typeUses' | 'entrypoint' | 'unresolved' | 'textMatch' | 'structuralMatch';
+export type EvidenceFlag = 'same-file' | 'external' | 'type-only' | 'test-only' | 'dynamic' | 'string-only' | 'unreachable' | 'generated' | 'declaration';
+export interface EvidenceFact {
+    id: string;
+    subject: EvidenceSubject;
+    claim: EvidenceClaim;
+    source: EvidenceSource;
+    confidence: EvidenceConfidence;
+    flags?: EvidenceFlag[];
+    value?: unknown;
+}
+export type EvidenceRelation = 'contains' | 'defines' | 'exports' | 'imports' | 'references' | 'calls' | 'constructs' | 'extends' | 'implements' | 'typeUses' | 'retains' | 'reachableFrom' | 'declaresDependency' | 'usesDependency';
+export interface EvidenceEdge {
+    id: string;
+    from: EvidenceSubject;
+    to: EvidenceSubject;
+    relation: EvidenceRelation;
+    source: EvidenceSource;
+    confidence: EvidenceConfidence;
+    flags?: EvidenceFlag[];
+    via?: EvidenceLocation;
+}
+export type PacketVerdict = 'reachable' | 'candidate-dead' | 'transitive-dead' | 'candidate-unused-file' | 'candidate-unused-dependency' | 'unknown';
+export type PacketProofStatus = 'candidate' | 'confirmed-by-lsp' | 'confirmed-by-ast-and-lsp' | 'needs-framework-graph' | 'conflicting-evidence';
+export type MissingProofKind = 'lsp-unavailable' | 'dynamic-import-unresolved' | 'framework-entrypoint-unknown' | 'tsconfig-paths-unresolved' | 'manifest-rule-missing' | 'parser-failed' | 'pagination-open';
+export interface MissingProof {
+    kind: MissingProofKind;
+    severity: 'low' | 'medium' | 'high';
+    location?: EvidenceLocation;
+}
+export interface ResearchEvidencePacket {
+    subject: EvidenceSubject;
+    verdict: PacketVerdict;
+    proofStatus: PacketProofStatus;
+    why: EvidenceFact[];
+    retainedBy: EvidenceEdge[];
+    retains?: EvidenceEdge[];
+    missingProof: MissingProof[];
+    proof?: Record<string, unknown>;
+    risk: {
+        deleteRisk: 'low' | 'medium' | 'high' | 'unknown';
+        reason: string;
+    };
+    next: Record<string, OqlContinuation>;
+}
+export interface ResearchGraphSummary {
+    subjects: number;
+    facts: number;
+    edges: number;
+    byVerdict: Record<PacketVerdict, number>;
+}
+export interface ResearchPacketBundle {
+    packets: ResearchEvidencePacket[];
+    graphSummary: ResearchGraphSummary;
+}