sdl-mcp 0.7.2 → 0.8.0

package/README.md

@@ -45,6 +45,8 @@ Instead of opening large files first, SDL-MCP indexes repositories into symbol c
 - Better relevance with dependency-aware context retrieval
 - Safer context access via policy controls and auditing
 - Faster iteration through incremental indexing and refresh workflows
+- KuzuDB-backed graph persistence means indexing happens once, not every session
+- Confidence-aware call resolution filtering and pass2 provenance in symbol cards and slices
 - Works across TypeScript, JavaScript, Python, Go, Java, C#, C, C++, PHP, Rust, Kotlin, and Shell
 
 ## Claude Opus 4.6 High Overview
@@ -70,7 +72,7 @@ Response: "# What is SDL-MCP?
   - **No awareness of what changed.** Every interaction starts from scratch with no incremental understanding.
 
   SDL-MCP addresses all three by maintaining a **persistent, indexed understanding** of your codebase and serving
-  context through a 4-rung escalation ladder.
+  context through the **Iris Gate Ladder**.
 
   ---
 
@@ -78,7 +80,7 @@ Response: "# What is SDL-MCP?
 
   ### 1. Symbol Indexing
 
-  SDL-MCP parses your TypeScript/JavaScript codebase using tree-sitter (or an optional Rust native indexer) and extracts
+  SDL-MCP parses your TypeScript/JavaScript codebase using a Rust native indexer by default, with the TypeScript tree-sitter path as fallback, and extracts
    every function, class, interface, type, and variable into **Symbol Cards** — compact metadata records containing the
   symbol's signature, a brief summary, dependency edges, and metrics like fan-in/out.
 
@@ -86,16 +88,16 @@ Response: "# What is SDL-MCP?
   dependency edges** tracked. A full card dump would cost ~2.3M tokens. The overview costs **825 tokens** — a **2,782x
   compression ratio**.
 
-  ### 2. The Context Ladder (4 Rungs)
+  ### 2. The Iris Gate Ladder (4 Rungs)
 
-  Instead of "here's the whole file," SDL-MCP provides context in escalating detail:
+  Instead of "here's the whole file," SDL-MCP provides context in escalating detail using the **Iris Gate Ladder**. This approach ensures AI agents have the minimum context needed to be effective, preserving your token budget.
 
-  | Rung | What You Get | Token Cost | When Used |
-  |------|-------------|------------|-----------|
-  | **Symbol Cards** | Name, signature, summary, dependencies | ~50 tokens | Always start here |
-  | **Skeleton IR** | Signatures + control flow, bodies elided | ~200 tokens | Understanding structure |
-  | **Hot-Path Excerpt** | Only lines matching specific identifiers | ~500 tokens | Finding specific logic |
-  | **Full Code Window** | Complete source (gated, requires justification) | ~2,000 tokens | Last resort |
+  | Rung | Tool | Est. Tokens | When Used |
+  |------|------|------------|-----------|
+  | **1. Symbol Cards** | `sdl.symbol.getCard` | ~50 tokens | Always start here: signatures, summaries, and dependencies. |
+  | **2. Skeleton IR** | `sdl.code.getSkeleton` | ~200 tokens | Understanding logic flow and structure without bodies. |
+  | **3. Hot-Path Excerpt** | `sdl.code.getHotPath` | ~500 tokens | Verifying specific identifier usage in context. |
+  | **4. Raw Code Window** | `sdl.code.needWindow` | ~2,000 tokens | Final escalation: policy-gated access to full source. |
 
   Most questions can be answered at rungs 1-2 without ever reading raw code.
 
@@ -132,7 +134,7 @@ Response: "# What is SDL-MCP?
 
   - Scales to thousands of files without blowing context windows
   - Symbol-level tracking survives whitespace changes and trivial refactors
-  - SQLite-backed persistence means indexing happens once, not every session
+  - KuzuDB-backed graph persistence means indexing happens once, not every session
 
   **For teams:**
 
@@ -147,7 +149,7 @@ Response: "# What is SDL-MCP?
   SDL-MCP runs as a CLI with 5 commands:
 
   ```bash
-  sdl-mcp init      # Create config + database
+  sdl-mcp init      # Create config + graph DB path
   sdl-mcp index     # Index your repositories
   sdl-mcp serve     # Start the MCP server (stdio or HTTP)
   sdl-mcp doctor    # Health check
@@ -203,9 +205,12 @@ sdl-mcp serve --stdio --no-watch
 ## Core Feature Set
 
 - Multi-language repository indexing with tree-sitter adapters
-- Optional native Rust pass-1 indexing engine (`indexing.engine: "rust"`)
+- Native Rust pass-1 indexing engine by default (`indexing.engine: "rust"`, with TypeScript fallback)
+- Live editor-buffer indexing with draft-aware symbol/search/slice reads, save-time Kuzu patching, background reconciliation, and automatic checkpoint compaction (`liveIndex.*`)
 - Symbol cards with signatures, deps, metrics, and versioning
 - Graph slices with handles, leases, refresh, and spillover
+- Graph enrichment: clusters (community detection) + processes (call-chain traces) surfaced in cards/slices/overview/blast radius
+- Generalized pass2 resolver registry with TypeScript/JavaScript semantic pass2 plus Go pass2, and confidence-scored call metadata available through `symbol.getCard` and `slice.build`
 - Delta analysis and blast radius support with amplifier scoring
 - Semantic symbol search reranking (`sdl.symbol.search` with `semantic: true`)
 - LLM-generated symbol summaries with configurable concurrency and batching (`semantic.summaryModel`, `summaryMaxConcurrency`, `summaryBatchSize`)
@@ -216,6 +221,7 @@ sdl-mcp serve --stdio --no-watch
 - Agent orchestration tool (`sdl.agent.orchestrate`)
 - Predictive prefetch heuristics with status metrics (`prefetchStats`)
 - File watch debouncing for efficient incremental indexing (`indexing.watchDebounceMs`)
+- Live overlay controls for editor-buffer parsing and idle checkpointing (`liveIndex.debounceMs`, `liveIndex.idleCheckpointMs`, `liveIndex.maxDraftFiles`)
 - Canonical test mapping in symbol cards (`metrics.canonicalTest`)
 - Graph HTTP surface and browser explorer (`/api/graph/*`, `/ui/graph`)
 - VSCode extension MVP in `sdl-mcp-vscode/`
@@ -224,7 +230,7 @@ sdl-mcp serve --stdio --no-watch
 ## CLI Commands
 
 - `init` - bootstrap config and optional client template
-- `doctor` - validate runtime, config, DB path, grammars, repo access
+- `doctor` - validate runtime, config, DB path, grammars, repo access, and call-resolution capabilities
 - `index` - index repositories (optionally watch)
 - `serve` - run MCP server (`--stdio` or `--http`)
 - `export` - export sync artifact
@@ -251,6 +257,8 @@ See: [MCP Tools Reference](./docs/mcp-tools-reference.md)
 ## Documentation
 
 - [Documentation Hub](./docs/README.md)
+- [Iris Gate Ladder](./docs/IRIS_GATE_LADDER.md) - Context escalation methodology
+- [Architecture](./docs/ARCHITECTURE.md) - Tech stack and data flow
 - [Getting Started](./docs/getting-started.md)
 - [CLI Reference](./docs/cli-reference.md)
 - [MCP Tools Reference](./docs/mcp-tools-reference.md)

package/config/benchmark.ci.config.json

@@ -4,16 +4,16 @@
   "thresholds": {
     "indexing": {
       "indexTimePerFile": {
-        "maxMs": 350,
+        "maxMs": 2500,
         "trend": "lower-is-better",
-        "allowableIncreasePercent": 15,
-        "_comment": "Raised from 220 ms (v0.6.9b): canonical-test BFS is now O(edges) via batch pass, but CI runner variance warrants ~75 % headroom above the ~198 ms zod-oss baseline."
+        "allowableIncreasePercent": 30,
+        "_comment": "Raised for KuzuDB graph backend: graph writes are inherently slower than SQLite inserts. CI runners see ~1500-1700ms per file."
       },
       "indexTimePerSymbol": {
-        "maxMs": 20,
+        "maxMs": 150,
         "trend": "lower-is-better",
-        "allowableIncreasePercent": 60,
-        "_comment": "Raised from 15 ms: TS call-resolver adds per-symbol resolution work. Absolute cap still guards against catastrophic regressions."
+        "allowableIncreasePercent": 30,
+        "_comment": "Raised for KuzuDB graph backend: per-symbol graph operations cost more than SQLite row inserts."
       }
     },
     "quality": {
@@ -47,9 +47,9 @@
         "_comment": "Raised from 200 ms: TS call-resolver creates more edges (import aliases, barrel re-exports), making graph loading and beam-search proportionally slower."
       },
       "avgSkeletonTimeMs": {
-        "maxMs": 5,
+        "maxMs": 10,
         "trend": "lower-is-better",
-        "allowableIncreasePercent": 30
+        "allowableIncreasePercent": 50
       }
     },
     "tokenEfficiency": {
@@ -78,8 +78,8 @@
     }
   },
   "smoothing": {
-    "warmupRuns": 2,
-    "sampleRuns": 3,
+    "warmupRuns": 0,
+    "sampleRuns": 2,
     "outlierMethod": "iqr",
     "iqrMultiplier": 1.5
   },

package/config/benchmark.ci.windows.config.json

@@ -4,14 +4,16 @@
   "thresholds": {
     "indexing": {
       "indexTimePerFile": {
-        "maxMs": 800,
+        "maxMs": 8000,
         "trend": "lower-is-better",
-        "allowableIncreasePercent": 20
+        "allowableIncreasePercent": 30,
+        "_comment": "Raised for KuzuDB graph backend: Windows CI runners see ~4500-6000ms per file."
       },
       "indexTimePerSymbol": {
-        "maxMs": 30,
+        "maxMs": 500,
         "trend": "lower-is-better",
-        "allowableIncreasePercent": 80
+        "allowableIncreasePercent": 30,
+        "_comment": "Raised for KuzuDB graph backend: Windows graph operations cost more."
       }
     },
     "quality": {
@@ -43,9 +45,9 @@
         "allowableIncreasePercent": 150
       },
       "avgSkeletonTimeMs": {
-        "maxMs": 5,
+        "maxMs": 15,
         "trend": "lower-is-better",
-        "allowableIncreasePercent": 40
+        "allowableIncreasePercent": 50
       }
     },
     "tokenEfficiency": {
@@ -74,8 +76,8 @@
     }
   },
   "smoothing": {
-    "warmupRuns": 2,
-    "sampleRuns": 3,
+    "warmupRuns": 0,
+    "sampleRuns": 2,
     "outlierMethod": "iqr",
     "iqrMultiplier": 1.5
   },

package/config/sdlmcp.config.example.json

@@ -1,6 +1,5 @@
 {
   "$schema": "./sdlmcp.config.schema.json",
-
   "repos": [
     {
       "repoId": "my-repo",
@@ -14,10 +13,20 @@
         "**/coverage/**"
       ],
       "languages": [
-        "ts", "tsx", "js", "jsx",
-        "py", "go", "java", "cs",
-        "c", "cpp", "php", "rs",
-        "kt", "sh"
+        "ts",
+        "tsx",
+        "js",
+        "jsx",
+        "py",
+        "go",
+        "java",
+        "cs",
+        "c",
+        "cpp",
+        "php",
+        "rs",
+        "kt",
+        "sh"
       ],
       "maxFileBytes": 2000000,
       "includeNodeModulesTypes": true,
@@ -26,41 +35,42 @@
       "workspaceGlobs": null
     }
   ],
-
-  "dbPath": "./data/sdlmcp.sqlite",
-
   "policy": {
     "maxWindowLines": 180,
     "maxWindowTokens": 1400,
     "requireIdentifiers": true,
     "allowBreakGlass": true
   },
-
   "redaction": {
     "enabled": true,
     "includeDefaults": true,
     "patterns": []
   },
-
   "indexing": {
     "concurrency": 8,
     "enableFileWatching": true,
     "maxWatchedFiles": 25000,
     "workerPoolSize": null,
-    "engine": "typescript",
+    "engine": "rust",
     "watchDebounceMs": 300
   },
-
+  "liveIndex": {
+    "enabled": true,
+    "debounceMs": 75,
+    "idleCheckpointMs": 15000,
+    "maxDraftFiles": 200,
+    "reconcileConcurrency": 1,
+    "clusterRefreshThreshold": 25
+  },
   "slice": {
     "defaultMaxCards": 60,
     "defaultMaxTokens": 12000,
     "edgeWeights": {
-      "call": 1.0,
+      "call": 1,
       "import": 0.6,
       "config": 0.8
     }
   },
-
   "diagnostics": {
     "enabled": true,
     "mode": "tsLS",
@@ -68,7 +78,6 @@
     "timeoutMs": 2000,
     "scope": "changedFiles"
   },
-
   "cache": {
     "enabled": true,
     "symbolCardMaxEntries": 2000,
@@ -76,13 +85,11 @@
     "graphSliceMaxEntries": 1000,
     "graphSliceMaxSizeBytes": 52428800
   },
-
   "plugins": {
     "paths": [],
     "enabled": true,
     "strictVersioning": true
   },
-
   "semantic": {
     "enabled": true,
     "alpha": 0.6,
@@ -102,24 +109,24 @@
       "maxElements": 200000
     }
   },
-
   "prefetch": {
     "enabled": true,
     "maxBudgetPercent": 20,
     "warmTopN": 50
   },
-
   "tracing": {
     "enabled": false,
     "serviceName": "sdl-mcp",
     "exporterType": "console",
     "otlpEndpoint": null,
-    "sampleRate": 1.0
+    "sampleRate": 1
   },
-
   "parallelScorer": {
     "enabled": false,
     "poolSize": null,
     "minBatchSize": null
+  },
+  "graphDatabase": {
+    "path": "./data/sdl-mcp-graph.kuzu"
   }
 }

package/config/sdlmcp.config.json

@@ -106,7 +106,9 @@
       ]
     }
   ],
-  "dbPath": "./data/sdlmcp.sqlite",
+  "graphDatabase": {
+    "path": "./data/sdl-mcp-graph.kuzu"
+  },
   "policy": {
     "maxWindowLines": 180,
     "maxWindowTokens": 1400,

package/config/sdlmcp.config.json.sample

@@ -30,7 +30,9 @@
       "maxFileBytes": 2000000
     }
   ],
-  "dbPath": "F:\\Claude\\projects\\sdl-mcp\\sdl-mcp\\data\\sdlmcp.sqlite",
+  "graphDatabase": {
+    "path": "F:\\Claude\\projects\\sdl-mcp\\sdl-mcp\\data\\sdl-mcp-graph.kuzu"
+  },
   "policy": {
     "maxWindowLines": 180,
     "maxWindowTokens": 1400,

package/config/sdlmcp.config.schema.json

@@ -3,14 +3,20 @@
   "title": "SDL-MCP Configuration",
   "description": "Configuration schema for SDL-MCP (Symbol Delta Ledger MCP Server)",
   "type": "object",
-  "required": ["repos", "dbPath", "policy"],
+  "required": [
+    "repos",
+    "policy"
+  ],
   "properties": {
     "repos": {
       "type": "array",
       "description": "List of repositories to index",
       "items": {
         "type": "object",
-        "required": ["repoId", "rootPath"],
+        "required": [
+          "repoId",
+          "rootPath"
+        ],
         "properties": {
           "repoId": {
             "type": "string",
@@ -105,7 +111,7 @@
     },
     "dbPath": {
       "type": "string",
-      "description": "Path to SQLite database file",
+      "description": "Deprecated legacy SQLite database path (v0.7.x). Only used by the one-time SQLite→Kuzu migration script in v0.8.",
       "minLength": 1
     },
     "policy": {
@@ -133,6 +139,12 @@
           "type": "boolean",
           "description": "Allow break-glass mode to override policy temporarily",
           "default": true
+        },
+        "defaultMinCallConfidence": {
+          "type": "number",
+          "description": "Optional default minCallConfidence for symbol-card and slice call-edge filtering",
+          "minimum": 0,
+          "maximum": 1
         }
       },
       "default": {
@@ -161,7 +173,9 @@
           "description": "Custom redaction patterns",
           "items": {
             "type": "object",
-            "required": ["pattern"],
+            "required": [
+              "pattern"
+            ],
             "properties": {
               "name": {
                 "type": "string",
@@ -218,8 +232,11 @@
         "engine": {
           "type": "string",
           "description": "Pass-1 indexing engine implementation",
-          "enum": ["typescript", "rust"],
-          "default": "typescript"
+          "enum": [
+            "typescript",
+            "rust"
+          ],
+          "default": "rust"
         },
         "watchDebounceMs": {
           "type": "integer",
@@ -233,10 +250,64 @@
         "concurrency": 8,
         "enableFileWatching": true,
         "maxWatchedFiles": 25000,
-        "engine": "typescript",
+        "engine": "rust",
         "watchDebounceMs": 300
       }
     },
+    "liveIndex": {
+      "type": "object",
+      "description": "Live editor-buffer indexing and overlay reconciliation settings",
+      "properties": {
+        "enabled": {
+          "type": "boolean",
+          "description": "Enable live buffer indexing and draft-aware reads",
+          "default": true
+        },
+        "debounceMs": {
+          "type": "integer",
+          "description": "Debounce delay in milliseconds for editor buffer parse work",
+          "minimum": 25,
+          "maximum": 5000,
+          "default": 75
+        },
+        "idleCheckpointMs": {
+          "type": "integer",
+          "description": "Quiet-period threshold in milliseconds before idle checkpoint compaction runs",
+          "minimum": 1000,
+          "maximum": 300000,
+          "default": 15000
+        },
+        "maxDraftFiles": {
+          "type": "integer",
+          "description": "Maximum number of in-memory draft files allowed per repo",
+          "minimum": 1,
+          "maximum": 10000,
+          "default": 200
+        },
+        "reconcileConcurrency": {
+          "type": "integer",
+          "description": "Reserved concurrency cap for background reconciliation work",
+          "minimum": 1,
+          "maximum": 8,
+          "default": 1
+        },
+        "clusterRefreshThreshold": {
+          "type": "integer",
+          "description": "Touched-symbol threshold that should trigger broader cluster/process refresh behavior",
+          "minimum": 1,
+          "maximum": 1000,
+          "default": 25
+        }
+      },
+      "default": {
+        "enabled": true,
+        "debounceMs": 75,
+        "idleCheckpointMs": 15000,
+        "maxDraftFiles": 200,
+        "reconcileConcurrency": 1,
+        "clusterRefreshThreshold": 25
+      }
+    },
     "slice": {
       "type": "object",
       "description": "Graph slice configuration",
@@ -261,7 +332,7 @@
               "type": "number",
               "description": "Weight for call edges",
               "minimum": 0,
-              "default": 1.0
+              "default": 1
             },
             "import": {
               "type": "number",
@@ -277,7 +348,7 @@
             }
           },
           "default": {
-            "call": 1.0,
+            "call": 1,
             "import": 0.6,
             "config": 0.8
           }
@@ -287,7 +358,7 @@
         "defaultMaxCards": 60,
         "defaultMaxTokens": 12000,
         "edgeWeights": {
-          "call": 1.0,
+          "call": 1,
           "import": 0.6,
           "config": 0.8
         }
@@ -305,7 +376,10 @@
         "mode": {
           "type": "string",
           "description": "Diagnostics mode",
-          "enum": ["tsLS", "tsc"],
+          "enum": [
+            "tsLS",
+            "tsc"
+          ],
           "default": "tsLS"
         },
         "maxErrors": {
@@ -323,7 +397,10 @@
         "scope": {
           "type": "string",
           "description": "Diagnostics scope",
-          "enum": ["changedFiles", "workspace"],
+          "enum": [
+            "changedFiles",
+            "workspace"
+          ],
           "default": "changedFiles"
         }
       },
@@ -384,7 +461,9 @@
         "paths": {
           "type": "array",
           "description": "Paths to plugin entrypoints (files or directories)",
-          "items": { "type": "string" },
+          "items": {
+            "type": "string"
+          },
           "default": []
         },
         "enabled": {
@@ -421,7 +500,11 @@
         },
         "provider": {
           "type": "string",
-          "enum": ["api", "local", "mock"],
+          "enum": [
+            "api",
+            "local",
+            "mock"
+          ],
           "default": "mock"
         },
         "model": {
@@ -567,7 +650,11 @@
         "exporterType": {
           "type": "string",
           "description": "Exporter type for traces",
-          "enum": ["console", "otlp", "memory"],
+          "enum": [
+            "console",
+            "otlp",
+            "memory"
+          ],
           "default": "console"
         },
         "otlpEndpoint": {
@@ -614,6 +701,20 @@
       "default": {
         "enabled": false
       }
+    },
+    "graphDatabase": {
+      "type": "object",
+      "description": "KuzuDB graph database configuration for advanced graph queries",
+      "properties": {
+        "path": {
+          "type": [
+            "string",
+            "null"
+          ],
+          "description": "Path to the KuzuDB database file",
+          "default": null
+        }
+      }
     }
   }
 }

package/dist/agent/orchestrator.d.ts

@@ -9,6 +9,7 @@ export declare class Orchestrator {
     private generateSummary;
     private generateAnswer;
     private createErrorResult;
+    private expandContextForClusters;
 }
 export declare const orchestrator: Orchestrator;
 //# sourceMappingURL=orchestrator.d.ts.map

package/dist/agent/orchestrator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agent/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAKpB,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,YAAY,CAAe;;IAO7B,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IA+C1D,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAetD,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;IAavB,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,iBAAiB;CA+B1B;AAED,eAAO,MAAM,YAAY,cAAqB,CAAC"}
+{"version":3,"file":"orchestrator.d.ts","sourceRoot":"","sources":["../../src/agent/orchestrator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EACT,mBAAmB,EACnB,gBAAgB,EACjB,MAAM,YAAY,CAAC;AAOpB,qBAAa,YAAY;IACvB,OAAO,CAAC,OAAO,CAAU;IACzB,OAAO,CAAC,YAAY,CAAe;;IAO7B,WAAW,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAmD1D,IAAI,CAAC,IAAI,EAAE,SAAS,GAAG,OAAO,CAAC,gBAAgB,CAAC;IAetD,OAAO,CAAC,cAAc;IAItB,OAAO,CAAC,eAAe;IAkBvB,OAAO,CAAC,cAAc;IAuBtB,OAAO,CAAC,iBAAiB;YAgCX,wBAAwB;CAiDvC;AAED,eAAO,MAAM,YAAY,cAAqB,CAAC"}