@dreamtree-org/graphify 1.4.0 → 1.6.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,127 @@ 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;
+
+/**
+ * The slice of the Anthropic client this extractor uses — injectable so
+ * tests (and callers with pre-configured clients, custom base URLs, etc.)
+ * can substitute their own. Same DI pattern as DsnQueryFn / FileReader.
+ */
+interface SemanticModelClient {
+    messages: {
+        create(params: {
+            model: string;
+            max_tokens: number;
+            system: string;
+            thinking: {
+                type: 'adaptive';
+            };
+            output_config: {
+                format: {
+                    type: 'json_schema';
+                    schema: Record<string, unknown>;
+                };
+            };
+            messages: Array<{
+                role: 'user';
+                content: string;
+            }>;
+        }): Promise<{
+            stop_reason: string | null;
+            content: Array<{
+                type: string;
+                text?: string;
+            }>;
+        }>;
+    };
+}
+interface AnthropicSemanticExtractorOptions {
+    /** Pre-configured client (or a fake for tests). Wins over apiKey. */
+    client?: SemanticModelClient;
+    /**
+     * Explicit API key. Omitted = the SDK's own resolution (ANTHROPIC_API_KEY
+     * env var, auth token, or an `ant auth login` profile) — graphify never
+     * stores or defaults a key of its own.
+     */
+    apiKey?: string;
+    model?: string;
+    maxTokens?: number;
+}
+/**
+ * Direct-API semantic extraction via @anthropic-ai/sdk, for non-agent
+ * environments (e.g. a KB provider's ingest worker calling
+ * ingestDocument({semanticExtractor}) — docs/KB-PROVIDER.md §5). The
+ * default flow (Claude Code driving this CLI via the installed skill)
+ * still does its semantic pass through the assistant itself.
+ *
+ * Emits: one `entity`-kind node per extracted entity, an INFERRED
+ * `references` edge from the document node (id = `path`, matching
+ * ingestDocument's document node) to each entity, and INFERRED
+ * `references` edges between entities the document connects. Document
+ * content goes through security.wrapUntrustedSource() — never spliced raw
+ * into the prompt.
+ */
+declare class AnthropicSemanticExtractor implements SemanticExtractor {
+    private readonly client;
+    private readonly model;
+    private readonly maxTokens;
+    constructor(options?: AnthropicSemanticExtractorOptions);
+    extractSemantic(path: string, content: string): Promise<ExtractionResult>;
+}
+
+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,
@@ -731,6 +941,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;
@@ -747,6 +958,7 @@ declare const ExtractionResultSchema: z.ZodObject<{
             contains: "contains";
             method: "method";
             re_exports: "re_exports";
+            follows: "follows";
         }>;
         confidence: z.ZodEnum<{
             EXTRACTED: "EXTRACTED";
@@ -772,4 +984,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 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, 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 SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, expandRetrieval, 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, AnthropicSemanticExtractor, type AnthropicSemanticExtractorOptions, 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 SemanticModelClient, 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,127 @@ 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;
+
+/**
+ * The slice of the Anthropic client this extractor uses — injectable so
+ * tests (and callers with pre-configured clients, custom base URLs, etc.)
+ * can substitute their own. Same DI pattern as DsnQueryFn / FileReader.
+ */
+interface SemanticModelClient {
+    messages: {
+        create(params: {
+            model: string;
+            max_tokens: number;
+            system: string;
+            thinking: {
+                type: 'adaptive';
+            };
+            output_config: {
+                format: {
+                    type: 'json_schema';
+                    schema: Record<string, unknown>;
+                };
+            };
+            messages: Array<{
+                role: 'user';
+                content: string;
+            }>;
+        }): Promise<{
+            stop_reason: string | null;
+            content: Array<{
+                type: string;
+                text?: string;
+            }>;
+        }>;
+    };
+}
+interface AnthropicSemanticExtractorOptions {
+    /** Pre-configured client (or a fake for tests). Wins over apiKey. */
+    client?: SemanticModelClient;
+    /**
+     * Explicit API key. Omitted = the SDK's own resolution (ANTHROPIC_API_KEY
+     * env var, auth token, or an `ant auth login` profile) — graphify never
+     * stores or defaults a key of its own.
+     */
+    apiKey?: string;
+    model?: string;
+    maxTokens?: number;
+}
+/**
+ * Direct-API semantic extraction via @anthropic-ai/sdk, for non-agent
+ * environments (e.g. a KB provider's ingest worker calling
+ * ingestDocument({semanticExtractor}) — docs/KB-PROVIDER.md §5). The
+ * default flow (Claude Code driving this CLI via the installed skill)
+ * still does its semantic pass through the assistant itself.
+ *
+ * Emits: one `entity`-kind node per extracted entity, an INFERRED
+ * `references` edge from the document node (id = `path`, matching
+ * ingestDocument's document node) to each entity, and INFERRED
+ * `references` edges between entities the document connects. Document
+ * content goes through security.wrapUntrustedSource() — never spliced raw
+ * into the prompt.
+ */
+declare class AnthropicSemanticExtractor implements SemanticExtractor {
+    private readonly client;
+    private readonly model;
+    private readonly maxTokens;
+    constructor(options?: AnthropicSemanticExtractorOptions);
+    extractSemantic(path: string, content: string): Promise<ExtractionResult>;
+}
+
+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,
@@ -731,6 +941,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;
@@ -747,6 +958,7 @@ declare const ExtractionResultSchema: z.ZodObject<{
             contains: "contains";
             method: "method";
             re_exports: "re_exports";
+            follows: "follows";
         }>;
         confidence: z.ZodEnum<{
             EXTRACTED: "EXTRACTED";
@@ -772,4 +984,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 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, 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 SerializedGraph, type TestSelection, type TraversalEdge, type Violation, type VisitedNode, affectedBy, analyze, buildContextPack, buildGraph, checkRules, cluster, collectFiles, deserializeGraph, diffGraphs, expandRetrieval, 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, AnthropicSemanticExtractor, type AnthropicSemanticExtractorOptions, 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 SemanticModelClient, 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 };