@dreamtree-org/graphify 1.3.0 → 1.5.0

package/dist/index.d.cts

@@ -2,12 +2,18 @@ import Graph from 'graphology';
 import { z } from 'zod';
 
 type Confidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
-type Relation = 'calls' | 'imports' | 'imports_from' | 'inherits' | 'implements' | 'mixes_in' | 'embeds' | 'references' | 'contains' | 'method' | 're_exports';
+type Relation = 'calls' | 'imports' | 'imports_from' | 'inherits' | 'implements' | 'mixes_in' | 'embeds' | 'references' | 'contains' | 'method' | 're_exports' | 'follows';
 interface GraphNode {
     id: string;
     label: string;
     sourceFile: string;
     sourceLocation: string;
+    /**
+     * Node kind for document graphs (document|section|chunk|entity — see
+     * docs/KB-PROVIDER.md §5). Optional and schema-additive: classic code
+     * nodes encode kind inside the label ("class Foo") and omit this.
+     */
+    kind?: string;
 }
 interface GraphEdge {
     source: string;
@@ -89,28 +95,111 @@ declare function extract(filePath: string, displayPath?: string): Promise<Extrac
  * same module) are kept as separate edges.
  */
 declare function buildGraph(extractions: ExtractionResult[]): Graph;
+/**
+ * The merge loop shared by buildGraph() (fresh graph) and
+ * updateCorpusGraph() (incremental, src/ingest/corpus.ts). Callers validate
+ * first — this assumes well-formed extractions. A node that already exists
+ * only as an auto-vivified placeholder (sourceFile '<unknown>') is upgraded
+ * in place when an extraction supplies the real node.
+ */
+declare function mergeExtractionsInto(graph: Graph, validated: ExtractionResult[]): void;
 
-interface ResolveOptions {
+/**
+ * Provider-agnostic interface for the semantic (LLM-driven) extraction
+ * pass. The first-class, tested path is Anthropic (see anthropic.ts) —
+ * this interface exists so an OpenAI-compatible endpoint can be swapped in
+ * later without redesigning callers. Do not build out a large provider
+ * matrix for v1 (see master prompt §7 v2 ideas).
+ */
+interface SemanticExtractor {
+    extractSemantic(path: string, content: string): Promise<ExtractionResult>;
+}
+
+/**
+ * Smart document ingestion (docs/KB-PROVIDER.md §5): replaces the flat
+ * `text -> string[]` chunker contract with `document -> { chunks + graph
+ * fragment }`. One document per call — providers ingest from queue workers
+ * a page at a time; updateCorpusGraph() (corpus.ts) folds each fragment
+ * into the corpus graph. Structural pass only: sections, chunks,
+ * contains/follows edges, and explicit relative markdown links — fully
+ * offline and deterministic. Entities in prose need the optional
+ * caller-injected SemanticExtractor.
+ */
+interface DocumentInput {
     /**
-     * The scanned package's own name(s) (from package.json). Tests very
-     * commonly import the package's PUBLIC entry (`import { persist } from
-     * 'zustand/middleware'`) rather than a relative path — without this,
-     * those land on an opaque `module:` node and the test never connects to
-     * the source it exercises (so `graphify tests` under-selects).
+     * Plain text or markdown. Binary parsing (PDF/DOCX/...) is the caller's
+     * job — this API takes extracted text.
      */
-    selfNames?: string[];
+    text: string;
+    /**
+     * Stable caller-side identity — becomes GraphNode.sourceFile and the id
+     * prefix for every node from this document. Re-ingesting the same
+     * sourceRef through updateCorpusGraph() replaces that document's subgraph.
+     */
+    sourceRef: string;
+    /** Routes the structural pass. Markdown headings are honored unless this says text/plain. */
+    mimeType?: string;
+    title?: string;
+    /** Echoed onto every chunk, never interpreted. */
+    metadata?: Record<string, string>;
+}
+interface ChunkOptions {
+    /** Soft target per chunk, in estimated tokens (~4 chars each). Default 400. */
+    targetTokens?: number;
+    /** Hard cap — over-long paragraphs are split to fit. Default 512. */
+    maxTokens?: number;
+    /**
+     * Overlap is OFF by default: `follows` edges + expandRetrieval() replace
+     * what sliding-window overlap approximates. Callers migrating from
+     * window-chunkers can turn it back on.
+     */
+    overlapTokens?: number;
 }
-interface ResolveStats {
-    /** Edge endpoints re-pointed from a guessed id to a real node id. */
-    resolvedEndpoints: number;
-    /** Placeholder module nodes dropped because the real file node replaced them. */
-    droppedPlaceholders: number;
+interface IngestOptions {
+    chunking?: ChunkOptions;
+    /**
+     * Optional semantic pass for entities/relationships in prose. Injected,
+     * never built-in — same stance as embeddings (docs/KB-PROVIDER.md §6).
+     * Omitted = structural-only, no LLM, no API key.
+     */
+    semanticExtractor?: SemanticExtractor;
+}
+interface IngestedChunk {
+    /**
+     * Graph node id of this chunk — store it next to the chunk row: it is
+     * what makes expandRetrieval() hits O(1) instead of lexical.
+     */
+    nodeId: string;
+    /** What the caller embeds and stores. */
+    content: string;
+    tokenEstimate: number;
+    /** Reading order within the document. */
+    index: number;
+    /** Heading trail, e.g. ["Q3 Results", "Revenue"]. Empty for plain text. */
+    sectionPath: string[];
+    /** sha256 of normalized content — caller-side dedup across sources. */
+    contentHash: string;
+    metadata: Record<string, string>;
+}
+interface IngestResult {
+    chunks: IngestedChunk[];
+    /** Graph fragment for this document — feed to updateCorpusGraph() or runPipeline's extraExtractions. */
+    extraction: ExtractionResult;
+    stats: {
+        sections: number;
+        entities: number;
+        tokenTotal: number;
+    };
 }
 /**
- * Mutates `extractions` in place: re-points guessed edge endpoints at real
- * node ids and drops the placeholder module nodes those guesses created.
+ * Turn one document into structure-aware chunks plus a typed graph
+ * fragment: a `document` node, `section` nodes nested via `contains`,
+ * `chunk` nodes under their section (`contains`), chained in reading order
+ * (`follows`), with relative markdown links as `references` edges. The
+ * chunks are graph nodes — the caller stores each chunk's nodeId, which is
+ * what fuses their vector search with expandRetrieval() at query time.
  */
-declare function resolveCrossFileReferences(extractions: ExtractionResult[], options?: ResolveOptions): ResolveStats;
+declare function ingestDocument(input: DocumentInput, options?: IngestOptions): Promise<IngestResult>;
 
 type ClusterAlgorithm = 'louvain' | 'leiden';
 interface ClusterOptions {
@@ -144,6 +233,60 @@ interface ClusterOptions {
  */
 declare function cluster(graph: Graph, options?: ClusterOptions): Graph;
 
+interface UpdateCorpusOptions {
+    algorithm?: ClusterAlgorithm;
+    /**
+     * Clustering strategy per update. `'auto'` (default) keeps bulk loading
+     * safe without the caller thinking about it: new nodes adopt the majority
+     * community of their neighbors (cheap, local, deterministic), and a full
+     * global re-cluster runs only when accumulated churn since the last full
+     * pass exceeds `reclusterRatio` of the graph — or on a never-clustered
+     * graph. `true` forces a full re-cluster now (e.g. once after a batch);
+     * `false` skips community maintenance entirely for this call (churn is
+     * still tracked, so a later `'auto'` call sees the backlog).
+     */
+    recluster?: boolean | 'auto';
+    /**
+     * Auto mode only: fraction of the graph's nodes that must have churned
+     * since the last full clustering before one is triggered. Default 0.1.
+     */
+    reclusterRatio?: number;
+}
+/**
+ * Fold one document's extraction into an existing corpus graph — the
+ * streaming-ingestion companion to ingestDocument() (docs/KB-PROVIDER.md
+ * §5). Pass null for the store.load() no-graph-yet case. Re-ingesting a
+ * document is replace-not-duplicate: every node whose sourceFile matches
+ * one of the extraction's sourceFiles is dropped (with its edges) before
+ * the fragment is merged. Placeholder nodes that earlier documents' link
+ * edges auto-vivified are upgraded in place when this document is the real
+ * thing. Community upkeep is incremental by default and self-tunes to bulk
+ * loads — see UpdateCorpusOptions.recluster. Mutates and returns the graph.
+ */
+declare function updateCorpusGraph(graph: Graph | null, extraction: ExtractionResult, options?: UpdateCorpusOptions): Graph;
+
+interface ResolveOptions {
+    /**
+     * The scanned package's own name(s) (from package.json). Tests very
+     * commonly import the package's PUBLIC entry (`import { persist } from
+     * 'zustand/middleware'`) rather than a relative path — without this,
+     * those land on an opaque `module:` node and the test never connects to
+     * the source it exercises (so `graphify tests` under-selects).
+     */
+    selfNames?: string[];
+}
+interface ResolveStats {
+    /** Edge endpoints re-pointed from a guessed id to a real node id. */
+    resolvedEndpoints: number;
+    /** Placeholder module nodes dropped because the real file node replaced them. */
+    droppedPlaceholders: number;
+}
+/**
+ * Mutates `extractions` in place: re-points guessed edge endpoints at real
+ * node ids and drops the placeholder module nodes those guesses created.
+ */
+declare function resolveCrossFileReferences(extractions: ExtractionResult[], options?: ResolveOptions): ResolveStats;
+
 /**
  * Surface god-nodes (excessive fan-in/out), structural surprises (self
  * references, AMBIGUOUS edges), and open questions (isolated nodes,
@@ -358,6 +501,73 @@ interface ExplainResult {
 /** Plain-language-ready explanation of the node that best matches `query`. */
 declare function explainNode(graph: Graph, query: string): ExplainResult | null;
 
+/**
+ * Graph-augmented retrieval (docs/KB-PROVIDER.md §4): the caller has
+ * already done similarity search (vector, keyword, hybrid — their
+ * pipeline, their embeddings); expandRetrieval() takes those hits and adds
+ * what similarity can't see — the nodes *structurally connected* to them.
+ * Pure and synchronous like every query function: Graph in, data out; no
+ * store access, no embedding calls.
+ */
+/**
+ * One hit from the caller's own search. `nodeId` when the caller stored
+ * graph node ids alongside its records at ingest time; otherwise `text`,
+ * resolved against the graph lexically (same resolver queryGraph uses).
+ */
+interface RetrievalHit {
+    nodeId?: string;
+    text?: string;
+    /** The caller's similarity score, echoed through to rank seeds. */
+    score?: number;
+}
+interface ExpandOptions {
+    /** Approximate cap, in tokens (~4 chars each), on the result. Default 2000. */
+    tokenBudget?: number;
+    maxHops?: number;
+    /** Restrict traversal (and reported edges) to these relations, e.g. ['contains', 'references']. */
+    relations?: Relation[];
+}
+interface ExpandedNode {
+    id: string;
+    label: string;
+    /** Node kind attr (chunk|section|entity|document|...) — absent on classic code nodes. */
+    kind?: string;
+    sourceFile: string;
+    sourceLocation: string;
+    /** 0 = was a seed (or an unresolvable hit echoed through). */
+    hops: number;
+    /** The edge that first led the traversal here (absent for seeds). */
+    via?: TraversalEdge;
+    /** The caller's similarity score — seeds only. */
+    seedScore?: number;
+}
+interface ExpandedContext {
+    /**
+     * Union of seed nodes and discovered neighbors, ranked: seeds first (by
+     * caller score desc), then by (hops asc, degree desc). Deduped across
+     * seeds. Hits that resolve to no graph node are echoed through with
+     * hops 0 and no expansion, so adopting this on a partially-ingested
+     * corpus never does worse than flat retrieval.
+     */
+    nodes: ExpandedNode[];
+    /** Every edge between included nodes — provenance for citations. */
+    edges: TraversalEdge[];
+    communities: Array<{
+        id: number;
+        label: string;
+        seedCount: number;
+    }>;
+    /** True when the token budget stopped the traversal before the frontier was exhausted. */
+    truncated: boolean;
+}
+/**
+ * Expand the caller's top-K hits through the graph: one joint,
+ * token-budgeted BFS seeded from every hit at once, so overlapping
+ * neighborhoods dedupe and the budget is shared across seeds. Deterministic
+ * (lexical neighbor order, stable ranking) like the rest of the query layer.
+ */
+declare function expandRetrieval(graph: Graph, hits: RetrievalHit[], options?: ExpandOptions): ExpandedContext;
+
 interface AffectedNode {
     id: string;
     label: string;
@@ -664,6 +874,7 @@ declare const ExtractionResultSchema: z.ZodObject<{
         label: z.ZodString;
         sourceFile: z.ZodString;
         sourceLocation: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     edges: z.ZodArray<z.ZodObject<{
         source: z.ZodString;
@@ -680,6 +891,7 @@ declare const ExtractionResultSchema: z.ZodObject<{
             contains: "contains";
             method: "method";
             re_exports: "re_exports";
+            follows: "follows";
         }>;
         confidence: z.ZodEnum<{
             EXTRACTED: "EXTRACTED";
@@ -705,4 +917,4 @@ declare class ExtractionValidationError extends Error {
  */
 declare function validateExtraction(value: unknown, context?: string): ExtractionResult;
 
-export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type GraphStore, type ImpactOptions, type ImpactResult, LocalFileGraphStore, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RewiredSymbol, type RulesConfig, type SavedResult, type SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, serializeGraph, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };
+export { type AffectedNode, type Analysis, type ChangedSymbol, type ChunkOptions, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DocumentInput, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExpandOptions, type ExpandedContext, type ExpandedNode, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type GraphStore, type ImpactOptions, type ImpactResult, type IngestOptions, type IngestResult, type IngestedChunk, LocalFileGraphStore, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RetrievalHit, type RewiredSymbol, type RulesConfig, type SavedResult, type SemanticExtractor, type SerializedGraph, type TestSelection, type TraversalEdge, type UpdateCorpusOptions, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, expandRetrieval, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, ingestDocument, isTestFile, loadGraph, loadResults, mergeExtractionsInto, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, serializeGraph, shortestPath, testsForChangedFiles, testsForNode, updateCorpusGraph, validateExtraction, validateRules };

package/dist/index.d.ts

@@ -2,12 +2,18 @@ import Graph from 'graphology';
 import { z } from 'zod';
 
 type Confidence = 'EXTRACTED' | 'INFERRED' | 'AMBIGUOUS';
-type Relation = 'calls' | 'imports' | 'imports_from' | 'inherits' | 'implements' | 'mixes_in' | 'embeds' | 'references' | 'contains' | 'method' | 're_exports';
+type Relation = 'calls' | 'imports' | 'imports_from' | 'inherits' | 'implements' | 'mixes_in' | 'embeds' | 'references' | 'contains' | 'method' | 're_exports' | 'follows';
 interface GraphNode {
     id: string;
     label: string;
     sourceFile: string;
     sourceLocation: string;
+    /**
+     * Node kind for document graphs (document|section|chunk|entity — see
+     * docs/KB-PROVIDER.md §5). Optional and schema-additive: classic code
+     * nodes encode kind inside the label ("class Foo") and omit this.
+     */
+    kind?: string;
 }
 interface GraphEdge {
     source: string;
@@ -89,28 +95,111 @@ declare function extract(filePath: string, displayPath?: string): Promise<Extrac
  * same module) are kept as separate edges.
  */
 declare function buildGraph(extractions: ExtractionResult[]): Graph;
+/**
+ * The merge loop shared by buildGraph() (fresh graph) and
+ * updateCorpusGraph() (incremental, src/ingest/corpus.ts). Callers validate
+ * first — this assumes well-formed extractions. A node that already exists
+ * only as an auto-vivified placeholder (sourceFile '<unknown>') is upgraded
+ * in place when an extraction supplies the real node.
+ */
+declare function mergeExtractionsInto(graph: Graph, validated: ExtractionResult[]): void;
 
-interface ResolveOptions {
+/**
+ * Provider-agnostic interface for the semantic (LLM-driven) extraction
+ * pass. The first-class, tested path is Anthropic (see anthropic.ts) —
+ * this interface exists so an OpenAI-compatible endpoint can be swapped in
+ * later without redesigning callers. Do not build out a large provider
+ * matrix for v1 (see master prompt §7 v2 ideas).
+ */
+interface SemanticExtractor {
+    extractSemantic(path: string, content: string): Promise<ExtractionResult>;
+}
+
+/**
+ * Smart document ingestion (docs/KB-PROVIDER.md §5): replaces the flat
+ * `text -> string[]` chunker contract with `document -> { chunks + graph
+ * fragment }`. One document per call — providers ingest from queue workers
+ * a page at a time; updateCorpusGraph() (corpus.ts) folds each fragment
+ * into the corpus graph. Structural pass only: sections, chunks,
+ * contains/follows edges, and explicit relative markdown links — fully
+ * offline and deterministic. Entities in prose need the optional
+ * caller-injected SemanticExtractor.
+ */
+interface DocumentInput {
     /**
-     * The scanned package's own name(s) (from package.json). Tests very
-     * commonly import the package's PUBLIC entry (`import { persist } from
-     * 'zustand/middleware'`) rather than a relative path — without this,
-     * those land on an opaque `module:` node and the test never connects to
-     * the source it exercises (so `graphify tests` under-selects).
+     * Plain text or markdown. Binary parsing (PDF/DOCX/...) is the caller's
+     * job — this API takes extracted text.
      */
-    selfNames?: string[];
+    text: string;
+    /**
+     * Stable caller-side identity — becomes GraphNode.sourceFile and the id
+     * prefix for every node from this document. Re-ingesting the same
+     * sourceRef through updateCorpusGraph() replaces that document's subgraph.
+     */
+    sourceRef: string;
+    /** Routes the structural pass. Markdown headings are honored unless this says text/plain. */
+    mimeType?: string;
+    title?: string;
+    /** Echoed onto every chunk, never interpreted. */
+    metadata?: Record<string, string>;
+}
+interface ChunkOptions {
+    /** Soft target per chunk, in estimated tokens (~4 chars each). Default 400. */
+    targetTokens?: number;
+    /** Hard cap — over-long paragraphs are split to fit. Default 512. */
+    maxTokens?: number;
+    /**
+     * Overlap is OFF by default: `follows` edges + expandRetrieval() replace
+     * what sliding-window overlap approximates. Callers migrating from
+     * window-chunkers can turn it back on.
+     */
+    overlapTokens?: number;
 }
-interface ResolveStats {
-    /** Edge endpoints re-pointed from a guessed id to a real node id. */
-    resolvedEndpoints: number;
-    /** Placeholder module nodes dropped because the real file node replaced them. */
-    droppedPlaceholders: number;
+interface IngestOptions {
+    chunking?: ChunkOptions;
+    /**
+     * Optional semantic pass for entities/relationships in prose. Injected,
+     * never built-in — same stance as embeddings (docs/KB-PROVIDER.md §6).
+     * Omitted = structural-only, no LLM, no API key.
+     */
+    semanticExtractor?: SemanticExtractor;
+}
+interface IngestedChunk {
+    /**
+     * Graph node id of this chunk — store it next to the chunk row: it is
+     * what makes expandRetrieval() hits O(1) instead of lexical.
+     */
+    nodeId: string;
+    /** What the caller embeds and stores. */
+    content: string;
+    tokenEstimate: number;
+    /** Reading order within the document. */
+    index: number;
+    /** Heading trail, e.g. ["Q3 Results", "Revenue"]. Empty for plain text. */
+    sectionPath: string[];
+    /** sha256 of normalized content — caller-side dedup across sources. */
+    contentHash: string;
+    metadata: Record<string, string>;
+}
+interface IngestResult {
+    chunks: IngestedChunk[];
+    /** Graph fragment for this document — feed to updateCorpusGraph() or runPipeline's extraExtractions. */
+    extraction: ExtractionResult;
+    stats: {
+        sections: number;
+        entities: number;
+        tokenTotal: number;
+    };
 }
 /**
- * Mutates `extractions` in place: re-points guessed edge endpoints at real
- * node ids and drops the placeholder module nodes those guesses created.
+ * Turn one document into structure-aware chunks plus a typed graph
+ * fragment: a `document` node, `section` nodes nested via `contains`,
+ * `chunk` nodes under their section (`contains`), chained in reading order
+ * (`follows`), with relative markdown links as `references` edges. The
+ * chunks are graph nodes — the caller stores each chunk's nodeId, which is
+ * what fuses their vector search with expandRetrieval() at query time.
  */
-declare function resolveCrossFileReferences(extractions: ExtractionResult[], options?: ResolveOptions): ResolveStats;
+declare function ingestDocument(input: DocumentInput, options?: IngestOptions): Promise<IngestResult>;
 
 type ClusterAlgorithm = 'louvain' | 'leiden';
 interface ClusterOptions {
@@ -144,6 +233,60 @@ interface ClusterOptions {
  */
 declare function cluster(graph: Graph, options?: ClusterOptions): Graph;
 
+interface UpdateCorpusOptions {
+    algorithm?: ClusterAlgorithm;
+    /**
+     * Clustering strategy per update. `'auto'` (default) keeps bulk loading
+     * safe without the caller thinking about it: new nodes adopt the majority
+     * community of their neighbors (cheap, local, deterministic), and a full
+     * global re-cluster runs only when accumulated churn since the last full
+     * pass exceeds `reclusterRatio` of the graph — or on a never-clustered
+     * graph. `true` forces a full re-cluster now (e.g. once after a batch);
+     * `false` skips community maintenance entirely for this call (churn is
+     * still tracked, so a later `'auto'` call sees the backlog).
+     */
+    recluster?: boolean | 'auto';
+    /**
+     * Auto mode only: fraction of the graph's nodes that must have churned
+     * since the last full clustering before one is triggered. Default 0.1.
+     */
+    reclusterRatio?: number;
+}
+/**
+ * Fold one document's extraction into an existing corpus graph — the
+ * streaming-ingestion companion to ingestDocument() (docs/KB-PROVIDER.md
+ * §5). Pass null for the store.load() no-graph-yet case. Re-ingesting a
+ * document is replace-not-duplicate: every node whose sourceFile matches
+ * one of the extraction's sourceFiles is dropped (with its edges) before
+ * the fragment is merged. Placeholder nodes that earlier documents' link
+ * edges auto-vivified are upgraded in place when this document is the real
+ * thing. Community upkeep is incremental by default and self-tunes to bulk
+ * loads — see UpdateCorpusOptions.recluster. Mutates and returns the graph.
+ */
+declare function updateCorpusGraph(graph: Graph | null, extraction: ExtractionResult, options?: UpdateCorpusOptions): Graph;
+
+interface ResolveOptions {
+    /**
+     * The scanned package's own name(s) (from package.json). Tests very
+     * commonly import the package's PUBLIC entry (`import { persist } from
+     * 'zustand/middleware'`) rather than a relative path — without this,
+     * those land on an opaque `module:` node and the test never connects to
+     * the source it exercises (so `graphify tests` under-selects).
+     */
+    selfNames?: string[];
+}
+interface ResolveStats {
+    /** Edge endpoints re-pointed from a guessed id to a real node id. */
+    resolvedEndpoints: number;
+    /** Placeholder module nodes dropped because the real file node replaced them. */
+    droppedPlaceholders: number;
+}
+/**
+ * Mutates `extractions` in place: re-points guessed edge endpoints at real
+ * node ids and drops the placeholder module nodes those guesses created.
+ */
+declare function resolveCrossFileReferences(extractions: ExtractionResult[], options?: ResolveOptions): ResolveStats;
+
 /**
  * Surface god-nodes (excessive fan-in/out), structural surprises (self
  * references, AMBIGUOUS edges), and open questions (isolated nodes,
@@ -358,6 +501,73 @@ interface ExplainResult {
 /** Plain-language-ready explanation of the node that best matches `query`. */
 declare function explainNode(graph: Graph, query: string): ExplainResult | null;
 
+/**
+ * Graph-augmented retrieval (docs/KB-PROVIDER.md §4): the caller has
+ * already done similarity search (vector, keyword, hybrid — their
+ * pipeline, their embeddings); expandRetrieval() takes those hits and adds
+ * what similarity can't see — the nodes *structurally connected* to them.
+ * Pure and synchronous like every query function: Graph in, data out; no
+ * store access, no embedding calls.
+ */
+/**
+ * One hit from the caller's own search. `nodeId` when the caller stored
+ * graph node ids alongside its records at ingest time; otherwise `text`,
+ * resolved against the graph lexically (same resolver queryGraph uses).
+ */
+interface RetrievalHit {
+    nodeId?: string;
+    text?: string;
+    /** The caller's similarity score, echoed through to rank seeds. */
+    score?: number;
+}
+interface ExpandOptions {
+    /** Approximate cap, in tokens (~4 chars each), on the result. Default 2000. */
+    tokenBudget?: number;
+    maxHops?: number;
+    /** Restrict traversal (and reported edges) to these relations, e.g. ['contains', 'references']. */
+    relations?: Relation[];
+}
+interface ExpandedNode {
+    id: string;
+    label: string;
+    /** Node kind attr (chunk|section|entity|document|...) — absent on classic code nodes. */
+    kind?: string;
+    sourceFile: string;
+    sourceLocation: string;
+    /** 0 = was a seed (or an unresolvable hit echoed through). */
+    hops: number;
+    /** The edge that first led the traversal here (absent for seeds). */
+    via?: TraversalEdge;
+    /** The caller's similarity score — seeds only. */
+    seedScore?: number;
+}
+interface ExpandedContext {
+    /**
+     * Union of seed nodes and discovered neighbors, ranked: seeds first (by
+     * caller score desc), then by (hops asc, degree desc). Deduped across
+     * seeds. Hits that resolve to no graph node are echoed through with
+     * hops 0 and no expansion, so adopting this on a partially-ingested
+     * corpus never does worse than flat retrieval.
+     */
+    nodes: ExpandedNode[];
+    /** Every edge between included nodes — provenance for citations. */
+    edges: TraversalEdge[];
+    communities: Array<{
+        id: number;
+        label: string;
+        seedCount: number;
+    }>;
+    /** True when the token budget stopped the traversal before the frontier was exhausted. */
+    truncated: boolean;
+}
+/**
+ * Expand the caller's top-K hits through the graph: one joint,
+ * token-budgeted BFS seeded from every hit at once, so overlapping
+ * neighborhoods dedupe and the budget is shared across seeds. Deterministic
+ * (lexical neighbor order, stable ranking) like the rest of the query layer.
+ */
+declare function expandRetrieval(graph: Graph, hits: RetrievalHit[], options?: ExpandOptions): ExpandedContext;
+
 interface AffectedNode {
     id: string;
     label: string;
@@ -664,6 +874,7 @@ declare const ExtractionResultSchema: z.ZodObject<{
         label: z.ZodString;
         sourceFile: z.ZodString;
         sourceLocation: z.ZodString;
+        kind: z.ZodOptional<z.ZodString>;
     }, z.core.$strip>>;
     edges: z.ZodArray<z.ZodObject<{
         source: z.ZodString;
@@ -680,6 +891,7 @@ declare const ExtractionResultSchema: z.ZodObject<{
             contains: "contains";
             method: "method";
             re_exports: "re_exports";
+            follows: "follows";
         }>;
         confidence: z.ZodEnum<{
             EXTRACTED: "EXTRACTED";
@@ -705,4 +917,4 @@ declare class ExtractionValidationError extends Error {
  */
 declare function validateExtraction(value: unknown, context?: string): ExtractionResult;
 
-export { type AffectedNode, type Analysis, type ChangedSymbol, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type GraphStore, type ImpactOptions, type ImpactResult, LocalFileGraphStore, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RewiredSymbol, type RulesConfig, type SavedResult, type SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, isTestFile, loadGraph, loadResults, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, serializeGraph, shortestPath, testsForChangedFiles, testsForNode, validateExtraction, validateRules };
+export { type AffectedNode, type Analysis, type ChangedSymbol, type ChunkOptions, type ClusterAlgorithm, type ClusterOptions, type Confidence, type ContextOptions, type ContextPack, type ContextSnippet, type DependencyRule, type DocumentInput, type DsnQueryFn, EXTRACTOR_REGISTRY, type ExpandOptions, type ExpandedContext, type ExpandedNode, type ExplainResult, type ExportOptions, ExtractionCache, type ExtractionResult, ExtractionResultSchema, ExtractionValidationError, type ExtractionValidationIssue, type FileCategory, type FileManifest, type GraphDiff, type GraphEdge, type GraphNode, type GraphStore, type ImpactOptions, type ImpactResult, type IngestOptions, type IngestResult, type IngestedChunk, LocalFileGraphStore, type MergeEntry, type NodeMatch, type PathResult, type PipelineOptions, type PipelineResult, type QueryOptions, type QueryResult, type ReflectOptions, type Relation, type ResolveStats, type ResultOutcome, type ResultType, type RetrievalHit, type RewiredSymbol, type RulesConfig, type SavedResult, type SemanticExtractor, type SerializedGraph, type TestSelection, type TraversalEdge, type UpdateCorpusOptions, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, expandRetrieval, explainNode, exportGraph, extract, extractMysql, globToRegExp, graphForDirectory, ingestDocument, isTestFile, loadGraph, loadResults, mergeExtractionsInto, mergeGraphs, queryGraph, rankForTask, renderContextPack, renderLessons, renderReport, renderReview, resolveCrossFileReferences, resolveNode, reviewRevisions, runPipeline, saveResult, scoreNodes, serializeGraph, shortestPath, testsForChangedFiles, testsForNode, updateCorpusGraph, validateExtraction, validateRules };