@swarmvaultai/engine 0.1.18 → 0.1.19

package/README.md

@@ -26,16 +26,20 @@ import {
   defaultVaultSchema,
   exploreVault,
   exportGraphHtml,
+  explainGraphVault,
   importInbox,
   ingestInput,
   initVault,
   installAgent,
   getWebSearchAdapterForTask,
   lintVault,
+  listGodNodes,
   listSchedules,
   loadVaultConfig,
   loadVaultSchema,
   loadVaultSchemas,
+  pathGraphVault,
+  queryGraphVault,
   queryVault,
   runSchedule,
   searchVault,
@@ -64,6 +68,9 @@ await compileVault(rootDir, {});
 const saved = await queryVault(rootDir, { question: "What changed most recently?" });
 console.log(saved.savedPath);
 
+const graphQuery = await queryGraphVault(rootDir, "Which nodes bridge the biggest communities?");
+console.log(graphQuery.summary);
+
 const exploration = await exploreVault(rootDir, { question: "What should I investigate next?", steps: 3, format: "report" });
 console.log(exploration.hubPath);
 
@@ -132,9 +139,14 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 ### Compile + Query
 
 - `compileVault(rootDir, { approve })` writes wiki pages, graph data, and search state using the vault schema as guidance, or stages a review bundle
+- compile also writes graph orientation pages such as `wiki/graph/report.md` and `wiki/graph/communities/<community>.md`
 - `queryVault(rootDir, { question, save, format, review })` answers against the compiled vault using the same schema layer and saves by default
 - `exploreVault(rootDir, { question, steps, format, review })` runs a save-first multi-step exploration loop and writes a hub page plus step outputs
 - `searchVault(rootDir, query, limit)` searches compiled pages directly
+- `queryGraphVault(rootDir, question, { traversal, budget })` runs deterministic local graph search without a model provider
+- `pathGraphVault(rootDir, from, to)` returns the shortest graph path between two targets
+- `explainGraphVault(rootDir, target)` returns node, community, neighbor, and provenance details
+- `listGodNodes(rootDir, limit)` returns the most connected bridge-heavy graph nodes
 - project-aware compile also builds `wiki/projects/index.md` plus `wiki/projects/<project>/index.md` rollups without duplicating page trees
 - human-authored insight pages in `wiki/insights/` are indexed into search and available to query without being rewritten by compile
 - `chart` and `image` formats save wrapper markdown pages plus local output assets under `wiki/outputs/assets/<slug>/`
@@ -159,7 +171,7 @@ This matters because many "OpenAI-compatible" backends only implement part of th
 - `startMcpServer(rootDir)` runs the MCP server over stdio
 - `exportGraphHtml(rootDir, outputPath)` exports the graph workspace as a standalone HTML file
 
-The MCP surface includes tools for workspace info, page search, page reads, source listing, querying, ingestion, compile, and lint, along with resources for config, graph, manifests, schema, page content, and session artifacts.
+The MCP surface includes tools for workspace info, page search, page reads, source listing, querying, ingestion, compile, lint, and graph-native read operations such as graph query, node explain, neighbor lookup, shortest path, and god-node listing, along with resources for config, graph, manifests, schema, page content, and session artifacts.
 
 ## Artifacts
 
@@ -170,6 +182,7 @@ Running the engine produces a local workspace with these main areas:
 - `raw/sources/`: immutable source copies
 - `raw/assets/`: copied attachments referenced by ingested markdown bundles and remote URL ingests
 - `wiki/`: generated markdown pages, the append-only `log.md` activity trail, staged candidates, saved query outputs, exploration hub pages, and a human-only `insights/` area
+- `wiki/graph/`: generated graph report pages and per-community summaries derived from `state/graph.json`
 - `wiki/outputs/assets/`: local chart/image artifacts and JSON manifests for saved visual outputs
 - `wiki/code/`: generated module pages for ingested code sources
 - `wiki/projects/`: generated project rollups over canonical pages
@@ -186,7 +199,7 @@ Running the engine produces a local workspace with these main areas:
 - `state/jobs.ndjson`: watch-mode automation logs
 
 Saved outputs are indexed immediately into the graph page registry and search index, then linked back into compiled source, concept, and entity pages immediately through the lightweight artifact sync path. New concept and entity pages stage into `wiki/candidates/` first and promote to active pages on the next matching compile. Insight pages are indexed into search and page reads, but compile does not mutate them. Project-scoped pages receive `project_ids`, project tags, and layered root-plus-project schema hashes when all contributing sources resolve to the same configured project.
-Code sources also emit module and symbol nodes into `state/graph.json`, so local imports, exports, inheritance, and same-module call edges are queryable through the same viewer and search pipeline.
+Code sources also emit module, symbol, and parser-backed rationale nodes into `state/graph.json`, so local imports, exports, inheritance, same-module call edges, and rationale links are queryable through the same viewer and search pipeline.
 Ingest, inbox import, compile, query, lint, review, and candidate operations also append human-readable entries to `wiki/log.md`.
 
 ## Notes

package/dist/index.d.ts

@@ -39,9 +39,10 @@ declare const agentTypeSchema: z.ZodEnum<{
     opencode: "opencode";
 }>;
 type AgentType = z.infer<typeof agentTypeSchema>;
-type PageKind = "index" | "source" | "module" | "concept" | "entity" | "output" | "insight";
+type PageKind = "index" | "source" | "module" | "concept" | "entity" | "output" | "insight" | "graph_report" | "community_summary";
 type Freshness = "fresh" | "stale";
 type ClaimStatus = "extracted" | "inferred" | "conflicted" | "stale";
+type EvidenceClass = "extracted" | "inferred" | "ambiguous";
 type Polarity = "positive" | "negative" | "neutral";
 type OutputOrigin = "query" | "explore";
 type OutputFormat = "markdown" | "report" | "slides" | "chart" | "image";
@@ -292,6 +293,13 @@ interface CodeAnalysis {
     exports: string[];
     diagnostics: CodeDiagnostic[];
 }
+interface SourceRationale {
+    id: string;
+    text: string;
+    citation: string;
+    kind: "docstring" | "comment" | "marker";
+    symbolName?: string;
+}
 interface CodeIndexEntry {
     sourceId: string;
     moduleId: string;
@@ -317,12 +325,13 @@ interface SourceAnalysis {
     entities: AnalyzedTerm[];
     claims: SourceClaim[];
     questions: string[];
+    rationales: SourceRationale[];
     code?: CodeAnalysis;
     producedAt: string;
 }
 interface GraphNode {
     id: string;
-    type: "source" | "concept" | "entity" | "module" | "symbol";
+    type: "source" | "concept" | "entity" | "module" | "symbol" | "rationale";
     label: string;
     pageId?: string;
     freshness?: Freshness;
@@ -343,6 +352,7 @@ interface GraphEdge {
     target: string;
     relation: string;
     status: ClaimStatus;
+    evidenceClass: EvidenceClass;
     confidence: number;
     provenance: string[];
 }
@@ -384,6 +394,56 @@ interface GraphArtifact {
     sources: SourceManifest[];
     pages: GraphPage[];
 }
+interface GraphQueryMatch {
+    type: "node" | "page";
+    id: string;
+    label: string;
+    score: number;
+}
+interface GraphQueryResult {
+    question: string;
+    traversal: "bfs" | "dfs";
+    seedNodeIds: string[];
+    seedPageIds: string[];
+    visitedNodeIds: string[];
+    visitedEdgeIds: string[];
+    pageIds: string[];
+    communities: string[];
+    summary: string;
+    matches: GraphQueryMatch[];
+}
+interface GraphPathResult {
+    from: string;
+    to: string;
+    resolvedFromNodeId?: string;
+    resolvedToNodeId?: string;
+    found: boolean;
+    nodeIds: string[];
+    edgeIds: string[];
+    pageIds: string[];
+    summary: string;
+}
+interface GraphExplainNeighbor {
+    nodeId: string;
+    label: string;
+    type: GraphNode["type"];
+    pageId?: string;
+    relation: string;
+    direction: "incoming" | "outgoing";
+    confidence: number;
+    evidenceClass: EvidenceClass;
+}
+interface GraphExplainResult {
+    target: string;
+    node: GraphNode;
+    page?: GraphPage;
+    community?: {
+        id: string;
+        label: string;
+    };
+    neighbors: GraphExplainNeighbor[];
+    summary: string;
+}
 interface ApprovalEntry {
     pageId: string;
     title: string;
@@ -778,6 +838,13 @@ declare function compileVault(rootDir: string, options?: CompileOptions): Promis
 declare function queryVault(rootDir: string, options: QueryOptions): Promise<QueryResult>;
 declare function exploreVault(rootDir: string, options: ExploreOptions): Promise<ExploreResult>;
 declare function searchVault(rootDir: string, query: string, limit?: number): Promise<SearchResult[]>;
+declare function queryGraphVault(rootDir: string, question: string, options?: {
+    traversal?: "bfs" | "dfs";
+    budget?: number;
+}): Promise<GraphQueryResult>;
+declare function pathGraphVault(rootDir: string, from: string, to: string): Promise<GraphPathResult>;
+declare function explainGraphVault(rootDir: string, target: string): Promise<GraphExplainResult>;
+declare function listGodNodes(rootDir: string, limit?: number): Promise<GraphNode[]>;
 declare function listPages(rootDir: string): Promise<GraphPage[]>;
 declare function readPage(rootDir: string, relativePath: string): Promise<{
     path: string;
@@ -814,4 +881,4 @@ declare function watchVault(rootDir: string, options?: WatchOptions): Promise<Wa
 declare function createWebSearchAdapter(id: string, config: WebSearchProviderConfig, rootDir: string): Promise<WebSearchAdapter>;
 declare function getWebSearchAdapterForTask(rootDir: string, task: "deepLintProvider"): Promise<WebSearchAdapter>;
 
-export { type AgentType, type AnalyzedTerm, type ApprovalChangeType, type ApprovalDetail, type ApprovalEntry, type ApprovalEntryDetail, type ApprovalEntryStatus, type ApprovalManifest, type ApprovalSummary, type CandidateRecord, type ChartDatum, type ChartSpec, type ClaimStatus, type CodeAnalysis, type CodeDiagnostic, type CodeImport, type CodeIndexArtifact, type CodeIndexEntry, type CodeLanguage, type CodeSymbol, type CodeSymbolKind, type CommandRoleExecutorConfig, type CompileOptions, type CompileResult, type CompileState, type DirectoryIngestResult, type DirectoryIngestSkip, type ExploreOptions, type ExploreResult, type ExploreStepResult, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GraphArtifact, type GraphEdge, type GraphNode, type GraphPage, type ImageGenerationRequest, type ImageGenerationResponse, type InboxImportResult, type InboxImportSkip, type IngestOptions, type InitOptions, type LintFinding, type LintOptions, type OrchestrationConfig, type OrchestrationFinding, type OrchestrationProposal, type OrchestrationRole, type OrchestrationRoleConfig, type OrchestrationRoleResult, type OutputAsset, type OutputAssetRole, type OutputFormat, type OutputOrigin, type PageKind, type PageManager, type PageStatus, type Polarity, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderRoleExecutorConfig, type ProviderType, type QueryOptions, type QueryResult, type ResolvedPaths, type ReviewActionResult, type RoleExecutorConfig, type SceneElement, type SceneSpec, type ScheduleController, type ScheduleJobConfig, type ScheduleStateRecord, type ScheduleTriggerConfig, type ScheduledCompileTask, type ScheduledExploreTask, type ScheduledLintTask, type ScheduledQueryTask, type ScheduledRunResult, type ScheduledTaskConfig, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceClaim, type SourceKind, type SourceManifest, type VaultConfig, type WatchController, type WatchOptions, type WatchRunRecord, type WebSearchAdapter, type WebSearchProviderConfig, type WebSearchProviderType, type WebSearchResult, acceptApproval, agentTypeSchema, archiveCandidate, assertProviderCapability, bootstrapDemo, compileVault, createMcpServer, createProvider, createWebSearchAdapter, defaultVaultConfig, defaultVaultSchema, exploreVault, exportGraphHtml, getProviderForTask, getWebSearchAdapterForTask, getWorkspaceInfo, importInbox, ingestDirectory, ingestInput, initVault, initWorkspace, installAgent, installConfiguredAgents, lintVault, listApprovals, listCandidates, listManifests, listPages, listSchedules, loadVaultConfig, loadVaultSchema, loadVaultSchemas, promoteCandidate, providerCapabilitySchema, providerTypeSchema, queryVault, readApproval, readExtractedText, readPage, rejectApproval, resolvePaths, runSchedule, searchVault, serveSchedules, startGraphServer, startMcpServer, watchVault, webSearchProviderTypeSchema };
+export { type AgentType, type AnalyzedTerm, type ApprovalChangeType, type ApprovalDetail, type ApprovalEntry, type ApprovalEntryDetail, type ApprovalEntryStatus, type ApprovalManifest, type ApprovalSummary, type CandidateRecord, type ChartDatum, type ChartSpec, type ClaimStatus, type CodeAnalysis, type CodeDiagnostic, type CodeImport, type CodeIndexArtifact, type CodeIndexEntry, type CodeLanguage, type CodeSymbol, type CodeSymbolKind, type CommandRoleExecutorConfig, type CompileOptions, type CompileResult, type CompileState, type DirectoryIngestResult, type DirectoryIngestSkip, type EvidenceClass, type ExploreOptions, type ExploreResult, type ExploreStepResult, type Freshness, type GenerationAttachment, type GenerationRequest, type GenerationResponse, type GraphArtifact, type GraphEdge, type GraphExplainNeighbor, type GraphExplainResult, type GraphNode, type GraphPage, type GraphPathResult, type GraphQueryMatch, type GraphQueryResult, type ImageGenerationRequest, type ImageGenerationResponse, type InboxImportResult, type InboxImportSkip, type IngestOptions, type InitOptions, type LintFinding, type LintOptions, type OrchestrationConfig, type OrchestrationFinding, type OrchestrationProposal, type OrchestrationRole, type OrchestrationRoleConfig, type OrchestrationRoleResult, type OutputAsset, type OutputAssetRole, type OutputFormat, type OutputOrigin, type PageKind, type PageManager, type PageStatus, type Polarity, type ProviderAdapter, type ProviderCapability, type ProviderConfig, type ProviderRoleExecutorConfig, type ProviderType, type QueryOptions, type QueryResult, type ResolvedPaths, type ReviewActionResult, type RoleExecutorConfig, type SceneElement, type SceneSpec, type ScheduleController, type ScheduleJobConfig, type ScheduleStateRecord, type ScheduleTriggerConfig, type ScheduledCompileTask, type ScheduledExploreTask, type ScheduledLintTask, type ScheduledQueryTask, type ScheduledRunResult, type ScheduledTaskConfig, type SearchResult, type SourceAnalysis, type SourceAttachment, type SourceClaim, type SourceKind, type SourceManifest, type SourceRationale, type VaultConfig, type WatchController, type WatchOptions, type WatchRunRecord, type WebSearchAdapter, type WebSearchProviderConfig, type WebSearchProviderType, type WebSearchResult, acceptApproval, agentTypeSchema, archiveCandidate, assertProviderCapability, bootstrapDemo, compileVault, createMcpServer, createProvider, createWebSearchAdapter, defaultVaultConfig, defaultVaultSchema, explainGraphVault, exploreVault, exportGraphHtml, getProviderForTask, getWebSearchAdapterForTask, getWorkspaceInfo, importInbox, ingestDirectory, ingestInput, initVault, initWorkspace, installAgent, installConfiguredAgents, lintVault, listApprovals, listCandidates, listGodNodes, listManifests, listPages, listSchedules, loadVaultConfig, loadVaultSchema, loadVaultSchemas, pathGraphVault, promoteCandidate, providerCapabilitySchema, providerTypeSchema, queryGraphVault, queryVault, readApproval, readExtractedText, readPage, rejectApproval, resolvePaths, runSchedule, searchVault, serveSchedules, startGraphServer, startMcpServer, watchVault, webSearchProviderTypeSchema };