@codragraph/cli 2.1.1 → 2.1.5

package/dist/core/search/bm25-index.js

@@ -69,76 +69,6 @@ const FALLBACK_FIELD_WEIGHTS = {
     content: 2,
     description: 1,
 };
-/**
- * Per-process cache for the MCP pool path: tracks which `(repoId, table)`
- * pairs have been ensured. The CLI/pipeline path gets its own cache inside
- * `cgdb-adapter.ts` keyed by table/index, scoped to the singleton connection.
- *
- * IMPORTANT: an entry is added ONLY when the index was confirmed to exist
- * (CREATE_FTS_INDEX succeeded, or failed with `'already exists'`). Other
- * failures (transient lock errors, missing extension, etc.) leave the key
- * unset so the next query retries instead of silently caching the failure.
- *
- * Entries for a given repoId are invalidated when its pool is closed —
- * see the `addPoolCloseListener` registration in `searchFTSFromCgdb`.
- */
-const ensuredPoolFTS = new Set();
-/**
- * Drop all ensured-FTS cache entries for a given repoId.
- *
- * Called from the pool-close listener so that a pool teardown / recreation
- * forces the next `searchFTSFromCgdb` call to re-issue `CREATE_FTS_INDEX`
- * against the fresh connection rather than trust stale ensure-state from a
- * previous pool lifetime.
- *
- * Exported for tests; the listener wiring is internal.
- */
-export function invalidateEnsuredFTSForRepo(repoId) {
-    const prefix = `${repoId}:`;
-    for (const key of ensuredPoolFTS) {
-        if (key.startsWith(prefix))
-            ensuredPoolFTS.delete(key);
-    }
-}
-/**
- * Tracks whether we've already wired the pool-close listener for this
- * process. The pool adapter is dynamically imported, so registration
- * happens lazily on the first MCP-pool-backed FTS query.
- */
-let poolCloseListenerRegistered = false;
-function registerPoolCloseListenerOnce(addPoolCloseListener) {
-    if (poolCloseListenerRegistered)
-        return;
-    poolCloseListenerRegistered = true;
-    addPoolCloseListener((repoId) => invalidateEnsuredFTSForRepo(repoId));
-}
-async function ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties) {
-    const key = `${repoId}:${table}:${indexName}`;
-    if (ensuredPoolFTS.has(key))
-        return;
-    const propList = properties.map((p) => `'${p}'`).join(', ');
-    try {
-        await executor(`CALL CREATE_FTS_INDEX('${table}', '${indexName}', [${propList}], stemmer := 'porter')`);
-        // Index was created successfully — safe to cache.
-        ensuredPoolFTS.add(key);
-    }
-    catch (e) {
-        // 'already exists' is the happy path (index persists on disk between
-        // process invocations) — cache it. Anything else is treated as a
-        // transient failure: surface a one-time warning and leave the key
-        // unset so the NEXT query retries rather than silently using a
-        // cached failure (which previously disabled BM25 for the whole
-        // process for that repo).
-        const msg = String(e?.message ?? '');
-        if (msg.includes('already exists')) {
-            ensuredPoolFTS.add(key);
-        }
-        else {
-            console.warn(`[codragraph] FTS index ensure failed for repo "${repoId}" table "${table}" ` +
-                `(index "${indexName}"): ${msg || e}. Will retry on next query.`);
-        }
-    }
-}
 /**
  * Execute a single FTS query via a custom executor (for MCP connection pool).
  * Returns the same shape as core queryFTS (from LadybugDB adapter).
@@ -254,23 +184,16 @@ export const searchFTSFromCgdb = async (query, limit = 20, repoId) => {
         // IMPORTANT: FTS queries run sequentially to avoid connection contention.
         // The MCP pool supports multiple connections, but FTS is best run serially.
         const poolMod = await import('../cgdb/pool-adapter.js');
-        const { executeQuery, addPoolCloseListener } = poolMod;
-        // Register the pool-close listener lazily on first use so a teardown of
-        // the pool entry (LRU eviction, idle timeout, explicit close) drops the
-        // matching `ensuredPoolFTS` entries. Without this, stale ensure-state
-        // can outlive the pool that produced it.
-        registerPoolCloseListenerOnce(addPoolCloseListener);
+        const { executeQuery } = poolMod;
         const executor = (cypher) => executeQuery(repoId, cypher);
-        // Lazy-create FTS indexes on first query for this repo (analyze no longer
-        // creates them up-front, so we ensure them here). Cached per-process.
-        // RFC 0001 Phase 2.5: drop `content` from FTS properties for repos
-        // analysed with --compress brotli|zstd — the column holds encoded
-        // bytes and would tokenise to garbage.
+        // The MCP/LocalBackend pool is opened read-only so it can safely coexist
+        // with `codragraph analyze`. Do not issue CREATE_FTS_INDEX here: when
+        // persisted FTS indexes are missing, QUERY_FTS_INDEX falls through to the
+        // bounded BM25 fallback below without noisy write-failure retries.
+        // RFC 0001 Phase 2.5: drop `content` from fallback scoring for repos
+        // analysed with --compress brotli|zstd — the column holds encoded bytes.
         const compress = await getCompressMode(repoId);
         const properties = ftsPropertiesFor(compress);
-        for (const { table, indexName } of FTS_TABLES) {
-            await ensureFTSIndexViaExecutor(executor, repoId, table, indexName, properties);
-        }
         fileResults = await queryFTSViaExecutor(executor, 'File', 'file_fts', query, limit);
         functionResults = await queryFTSViaExecutor(executor, 'Function', 'function_fts', query, limit);
         classResults = await queryFTSViaExecutor(executor, 'Class', 'class_fts', query, limit);

package/dist/core/search/hybrid-search.js

@@ -111,8 +111,16 @@ export const formatHybridResults = (results) => {
  * The semanticSearch function is injected to keep this module environment-agnostic.
  */
 export const hybridSearch = async (query, limit, executeQuery, semanticSearch) => {
-    // Use LadybugDB FTS for always-fresh BM25 results
-    const bm25Results = await searchFTSFromCgdb(query, limit);
-    const semanticResults = await semanticSearch(executeQuery, query, limit);
+    const bm25Promise = searchFTSFromCgdb(query, limit);
+    // Start semantic work immediately, but gate its DB calls behind BM25.
+    // semanticSearch performs embedding before it calls executeQuery, so this
+    // overlaps CPU/model work with BM25 while avoiding concurrent queries on the
+    // singleton LadybugDB connection used by CLI/HTTP paths.
+    const executeAfterBm25 = async (cypher) => {
+        await bm25Promise;
+        return executeQuery(cypher);
+    };
+    const semanticPromise = semanticSearch(executeAfterBm25, query, limit);
+    const [bm25Results, semanticResults] = await Promise.all([bm25Promise, semanticPromise]);
     return mergeWithRRF(bm25Results, semanticResults, limit);
 };

package/dist/mcp/local/local-backend.d.ts

@@ -186,7 +186,9 @@ export declare class LocalBackend {
      */
     private semanticSearch;
     executeCypher(repoName: string, query: string): Promise<any>;
+    private trySimpleGraphstoreNodeScan;
     private cypher;
+    private executeLabellessNodeScan;
     /**
      * Format raw Cypher result rows as a markdown table for LLM readability.
      * Falls back to raw result if rows aren't tabular objects.

package/dist/mcp/local/local-backend.js

@@ -79,6 +79,105 @@ export const VALID_NODE_LABELS = new Set([
     'Route',
     'Tool',
 ]);
+const SIMPLE_LABELLESS_MATCH_RE = /^MATCH\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*\)/i;
+const CYPHER_LIMIT_RE = /\bLIMIT\s+(\d+)\s*;?\s*$/i;
+const CYPHER_RELATION_RE = /--|-\[|\]-|->|<-/;
+const NATIVE_UNSAFE_NODE_LABELS = new Set(['Union']);
+function quoteKnownNodeLabels(query) {
+    return query;
+}
+function getNativeUnsafeNodeLabel(query) {
+    const labelRe = /\(\s*[A-Za-z_][A-Za-z0-9_]*\s*:\s*`?([A-Za-z_][A-Za-z0-9_]*)`?(?=[\s){])/g;
+    for (const match of query.matchAll(labelRe)) {
+        const label = match[1];
+        if (NATIVE_UNSAFE_NODE_LABELS.has(label))
+            return label;
+    }
+    return null;
+}
+function safeNodeLabelForCypher(typeOrLabel, nodeId) {
+    const explicit = typeof typeOrLabel === 'string' ? typeOrLabel.trim() : '';
+    if (explicit && VALID_NODE_LABELS.has(explicit) && !NATIVE_UNSAFE_NODE_LABELS.has(explicit)) {
+        return explicit;
+    }
+    const id = typeof nodeId === 'string' ? nodeId : '';
+    const fromId = id.includes(':') ? id.slice(0, id.indexOf(':')) : '';
+    if (fromId && VALID_NODE_LABELS.has(fromId) && !NATIVE_UNSAFE_NODE_LABELS.has(fromId)) {
+        return fromId;
+    }
+    return null;
+}
+function firstNonEmptyString(...values) {
+    for (const value of values) {
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value.trim();
+    }
+    return '';
+}
+function parseSimpleNodeScanQuery(query) {
+    const match = /^MATCH\s*\(\s*([A-Za-z_][A-Za-z0-9_]*)(?:\s*:\s*`?([A-Za-z_][A-Za-z0-9_]*)`?)?\s*\)\s*RETURN\s+(.+?)\s+LIMIT\s+(\d+)\s*;?\s*$/i.exec(query.trim());
+    if (!match)
+        return null;
+    const limit = Number.parseInt(match[4], 10);
+    if (!Number.isFinite(limit) || limit <= 0)
+        return null;
+    return {
+        alias: match[1],
+        label: match[2],
+        returnClause: match[3].trim(),
+        limit: Math.min(Math.trunc(limit), 1000),
+    };
+}
+function projectSimpleNodeRow(node, label, scan) {
+    const row = {};
+    const parts = scan.returnClause.split(/\s*,\s*/).filter(Boolean);
+    for (const part of parts) {
+        const asMatch = /^(.+?)\s+AS\s+([A-Za-z_][A-Za-z0-9_]*)$/i.exec(part.trim());
+        const expr = (asMatch?.[1] ?? part).trim();
+        const outKey = asMatch?.[2] ?? expr;
+        if (expr === scan.alias) {
+            row[outKey] = { ...node, _label: label };
+            continue;
+        }
+        const labelsMatch = new RegExp(`^labels\\(\\s*${scan.alias}\\s*\\)\\[0\\]$`, 'i').exec(expr);
+        if (labelsMatch) {
+            row[outKey] = label;
+            continue;
+        }
+        const propMatch = new RegExp(`^${scan.alias}\\.([A-Za-z_][A-Za-z0-9_]*)$`).exec(expr);
+        if (propMatch) {
+            row[outKey] = node[propMatch[1]];
+            continue;
+        }
+        return null;
+    }
+    return row;
+}
+function getSimpleLabellessNodeAlias(query) {
+    const trimmed = query.trim();
+    const match = SIMPLE_LABELLESS_MATCH_RE.exec(trimmed);
+    if (!match)
+        return null;
+    if (CYPHER_RELATION_RE.test(trimmed))
+        return null;
+    if (/\bMATCH\b/i.test(trimmed.slice(match[0].length)))
+        return null;
+    return match[1];
+}
+function getCypherLimit(query) {
+    const match = CYPHER_LIMIT_RE.exec(query);
+    if (!match)
+        return null;
+    const limit = Number.parseInt(match[1], 10);
+    return Number.isFinite(limit) && limit > 0 ? limit : null;
+}
+function withCypherLimit(query, limit) {
+    const safeLimit = Math.max(1, Math.trunc(limit));
+    if (CYPHER_LIMIT_RE.test(query)) {
+        return query.replace(CYPHER_LIMIT_RE, `LIMIT ${safeLimit}`);
+    }
+    return `${query.replace(/;\s*$/, '')} LIMIT ${safeLimit}`;
+}
 /** Valid relation types for impact analysis filtering */
 export const VALID_RELATION_TYPES = new Set([
     'CALLS',
@@ -1173,25 +1272,119 @@ export class LocalBackend {
         const repo = await this.resolveRepo(repoName);
         return this.cypher(repo, { query });
     }
-    async cypher(repo, params) {
-        await this.ensureInitialized(repo.id);
-        if (!isCgdbReady(repo.id)) {
-            return { error: 'LadybugDB not ready. Index may be corrupted.' };
+    async trySimpleGraphstoreNodeScan(repo, query) {
+        const scan = parseSimpleNodeScanQuery(query);
+        if (!scan)
+            return null;
+        if (scan.label && NATIVE_UNSAFE_NODE_LABELS.has(scan.label))
+            return [];
+        const objectsRoot = path.join(repo.storagePath, 'graphstore', 'objects');
+        try {
+            const stat = await fs.stat(objectsRoot);
+            if (!stat.isDirectory())
+                return null;
         }
+        catch {
+            return null;
+        }
+        const rows = [];
+        const visitDir = async (dir) => {
+            if (rows.length >= scan.limit)
+                return;
+            let entries;
+            try {
+                entries = await fs.readdir(dir, { withFileTypes: true });
+            }
+            catch {
+                return;
+            }
+            for (const entry of entries) {
+                if (rows.length >= scan.limit)
+                    return;
+                const entryPath = path.join(dir, entry.name);
+                if (entry.isDirectory()) {
+                    await visitDir(entryPath);
+                    continue;
+                }
+                if (!entry.isFile() || !entry.name.endsWith('.json'))
+                    continue;
+                try {
+                    const raw = await fs.readFile(entryPath, 'utf-8');
+                    const obj = JSON.parse(raw);
+                    const id = typeof obj.id === 'string' ? obj.id : '';
+                    if (!id || typeof obj.from === 'string' || typeof obj.to === 'string')
+                        continue;
+                    const label = id.includes(':') ? id.slice(0, id.indexOf(':')) : '';
+                    if (!label || (scan.label && label !== scan.label))
+                        continue;
+                    if (NATIVE_UNSAFE_NODE_LABELS.has(label))
+                        continue;
+                    const row = projectSimpleNodeRow(obj, label, scan);
+                    if (row)
+                        rows.push(row);
+                }
+                catch {
+                    // Ignore malformed graphstore objects; the native path remains available.
+                }
+            }
+        };
+        await visitDir(objectsRoot);
+        return rows;
+    }
+    async cypher(repo, params) {
         // Block write operations (defense-in-depth — DB is already read-only)
         if (isWriteQuery(params.query)) {
             return {
                 error: 'Write operations (CREATE, DELETE, SET, MERGE, REMOVE, DROP, ALTER, COPY, DETACH) are not allowed. The knowledge graph is read-only.',
             };
         }
+        const query = quoteKnownNodeLabels(params.query);
+        const unsafeLabel = getNativeUnsafeNodeLabel(query);
+        if (unsafeLabel) {
+            return [];
+        }
+        const graphstoreRows = await this.trySimpleGraphstoreNodeScan(repo, query);
+        if (graphstoreRows) {
+            return graphstoreRows;
+        }
+        await this.ensureInitialized(repo.id);
+        if (!isCgdbReady(repo.id)) {
+            return { error: 'LadybugDB not ready. Index may be corrupted.' };
+        }
+        const labellessAlias = getSimpleLabellessNodeAlias(query);
         try {
-            const result = await executeQuery(repo.id, params.query);
+            const result = labellessAlias
+                ? await this.executeLabellessNodeScan(repo.id, query, labellessAlias)
+                : await executeQuery(repo.id, query);
             return result;
         }
         catch (err) {
             return { error: err.message || 'Query failed' };
         }
     }
+    async executeLabellessNodeScan(repoId, query, alias) {
+        const limit = getCypherLimit(query) ?? 100;
+        const rows = [];
+        let lastError = null;
+        for (const label of VALID_NODE_LABELS) {
+            if (NATIVE_UNSAFE_NODE_LABELS.has(label))
+                continue;
+            if (rows.length >= limit)
+                break;
+            const labelQuery = withCypherLimit(query.replace(SIMPLE_LABELLESS_MATCH_RE, `MATCH (${alias}:\`${label}\`)`), limit - rows.length);
+            try {
+                const labelRows = await executeQuery(repoId, labelQuery);
+                rows.push(...labelRows);
+            }
+            catch (err) {
+                lastError = err instanceof Error ? err : new Error(String(err));
+            }
+        }
+        if (rows.length === 0 && lastError) {
+            throw lastError;
+        }
+        return rows.slice(0, limit);
+    }
     /**
      * Format raw Cypher result rows as a markdown table for LLM readability.
      * Falls back to raw result if rows aren't tabular objects.
@@ -1436,7 +1629,7 @@ export class LocalBackend {
             const symbol = {
                 id: (r.id ?? r[0]),
                 name: (r.name ?? r[1]),
-                type: (r.type ?? r[2] ?? ''),
+                type: firstNonEmptyString(r.type, r.__cgLabel, r[2]),
                 filePath: (r.filePath ?? r[3]),
                 startLine: (r.startLine ?? r[4]),
                 endLine: (r.endLine ?? r[5]),
@@ -1476,7 +1669,7 @@ export class LocalBackend {
         const normalized = rows.map((r) => ({
             id: (r.id ?? r[0]),
             name: (r.name ?? r[1]),
-            type: (r.type ?? r[2] ?? ''),
+            type: firstNonEmptyString(r.type, r.__cgLabel, r[2]),
             filePath: (r.filePath ?? r[3]),
             startLine: (r.startLine ?? r[4]),
             endLine: (r.endLine ?? r[5]),
@@ -2266,6 +2459,10 @@ export class LocalBackend {
         const impacted = [];
         const visited = new Set([symId]);
         let frontier = [symId];
+        const frontierTypes = new Map();
+        const symLabel = safeNodeLabelForCypher(symType, symId);
+        if (symLabel)
+            frontierTypes.set(symId, symLabel);
         let traversalComplete = true;
         // Fix #480: For Java (and other JVM) Class/Interface nodes, CALLS edges
         // point to Constructor nodes and IMPORTS edges point to File nodes — not
@@ -2279,16 +2476,16 @@ export class LocalBackend {
                 // Run both seed queries in parallel — they are independent.
                 const [ctorRows, fileRows] = await Promise.all([
                     executeParameterized(repo.id, `
-            MATCH (n)-[hm:CodeRelation]->(c:Constructor)
+            MATCH (n:${symLabel ?? symType})-[hm:CodeRelation]->(c:Constructor)
             WHERE n.id = $symId AND hm.type = 'HAS_METHOD'
-            RETURN c.id AS id, c.name AS name, labels(c)[0] AS type, c.filePath AS filePath
+            RETURN c.id AS id, c.name AS name, 'Constructor' AS type, c.filePath AS filePath
           `, { symId }),
                     // Restrict to DEFINES edges only — other File->Class edge types (if
                     // any) should not be treated as the owning file relationship.
                     executeParameterized(repo.id, `
-            MATCH (f:File)-[rel:CodeRelation]->(n)
+            MATCH (f:File)-[rel:CodeRelation]->(n:${symLabel ?? symType})
             WHERE n.id = $symId AND rel.type = 'DEFINES'
-            RETURN f.id AS id, f.name AS name, labels(f)[0] AS type, f.filePath AS filePath
+            RETURN f.id AS id, f.name AS name, 'File' AS type, f.filePath AS filePath
           `, { symId }),
                 ]);
                 for (const r of ctorRows) {
@@ -2296,6 +2493,9 @@ export class LocalBackend {
                     if (rid && !visited.has(rid)) {
                         visited.add(rid);
                         frontier.push(rid);
+                        const label = safeNodeLabelForCypher(r.type ?? r[2], rid);
+                        if (label)
+                            frontierTypes.set(rid, label);
                     }
                 }
                 for (const r of fileRows) {
@@ -2303,6 +2503,9 @@ export class LocalBackend {
                     if (rid && !visited.has(rid)) {
                         visited.add(rid);
                         frontier.push(rid);
+                        const label = safeNodeLabelForCypher(r.type ?? r[2], rid);
+                        if (label)
+                            frontierTypes.set(rid, label);
                     }
                 }
             }
@@ -2312,13 +2515,23 @@ export class LocalBackend {
         }
         for (let depth = 1; depth <= maxDepth && frontier.length > 0; depth++) {
             const nextFrontier = [];
-            // Batch frontier nodes into a single Cypher query per depth level
-            const idList = frontier.map((id) => `'${id.replace(/'/g, "''")}'`).join(', ');
-            const query = direction === 'upstream'
-                ? `MATCH (caller)-[r:CodeRelation]->(n) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, labels(caller)[0] AS type, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
-                : `MATCH (n)-[r:CodeRelation]->(callee) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, labels(callee)[0] AS type, callee.filePath AS filePath, r.type AS relType, r.confidence AS confidence`;
             try {
-                const related = await executeQuery(repo.id, query);
+                const frontierByLabel = new Map();
+                for (const id of frontier) {
+                    const label = frontierTypes.get(id) ?? safeNodeLabelForCypher(undefined, id) ?? '';
+                    const ids = frontierByLabel.get(label) ?? [];
+                    ids.push(id);
+                    frontierByLabel.set(label, ids);
+                }
+                const related = [];
+                for (const [label, ids] of frontierByLabel) {
+                    const idList = ids.map((id) => `'${id.replace(/'/g, "''")}'`).join(', ');
+                    const targetPattern = label ? `(n:${label})` : '(n)';
+                    const query = direction === 'upstream'
+                        ? `MATCH (caller)-[r:CodeRelation]->${targetPattern} WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, caller.id AS id, caller.name AS name, labels(caller)[0] AS type, caller.filePath AS filePath, r.type AS relType, r.confidence AS confidence`
+                        : `MATCH ${targetPattern}-[r:CodeRelation]->(callee) WHERE n.id IN [${idList}] AND r.type IN [${relTypeFilter}]${confidenceFilter} RETURN n.id AS sourceId, callee.id AS id, callee.name AS name, labels(callee)[0] AS type, callee.filePath AS filePath, r.type AS relType, r.confidence AS confidence`;
+                    related.push(...(await executeQuery(repo.id, query)));
+                }
                 for (const rel of related) {
                     const relId = rel.id || rel[1];
                     const filePath = rel.filePath || rel[4] || '';
@@ -2327,6 +2540,10 @@ export class LocalBackend {
                     if (!visited.has(relId)) {
                         visited.add(relId);
                         nextFrontier.push(relId);
+                        const relTypeLabel = firstNonEmptyString(rel.type, rel.__cgLabel, rel[3]);
+                        const relLabel = safeNodeLabelForCypher(relTypeLabel, relId);
+                        if (relLabel)
+                            frontierTypes.set(relId, relLabel);
                         const storedConfidence = rel.confidence ?? rel[6];
                         const relationType = rel.relType || rel[5];
                         // Prefer the stored confidence from the graph (set at analysis time);
@@ -2338,7 +2555,7 @@ export class LocalBackend {
                             depth,
                             id: relId,
                             name: rel.name || rel[2],
-                            type: rel.type || rel[3],
+                            type: relTypeLabel,
                             filePath,
                             relationType,
                             confidence: effectiveConfidence,

package/dist/mcp/resources.js

@@ -685,8 +685,8 @@ async function getSetupResource(backend) {
             '',
             '## Cross-platform commands',
             '',
-            '- Use `npx @codragraph/cli ...` or `codragraph ...` in Windows PowerShell, macOS bash/zsh, and Linux shells.',
-            '- Prefer `npm --prefix <package> <script>` from repo root for package checks instead of shell-specific `cd dir && ...` chains.',
+            '- Use `npx @codragraph/cli ...`, `bunx @codragraph/cli ...`, or `codragraph ...` in Windows PowerShell, macOS bash/zsh, and Linux shells.',
+            '- Prefer `npm --prefix <package> <script>` or `bun run --filter <workspace> <script>` from repo root for package checks instead of shell-specific `cd dir && ...` chains.',
         ];
         sections.push(lines.join('\n'));
     }

package/dist/server/api.d.ts

@@ -9,6 +9,7 @@
  */
 import express from 'express';
 import { type GraphNode, type GraphRelationship } from '../_shared/index.js';
+import { type WebDashboardMode } from './web-dashboard.js';
 /**
  * Determine whether an HTTP Origin header value is allowed by CORS policy.
  *
@@ -20,13 +21,16 @@ import { type GraphNode, type GraphRelationship } from '../_shared/index.js';
  *     10.0.0.0/8      → 10.x.x.x
  *     172.16.0.0/12   → 172.16.x.x – 172.31.x.x
  *     192.168.0.0/16  → 192.168.x.x
- * - https://codragraph.vercel.app — the deployed CodraGraph web UI
+ * - Hosted CodraGraph web UI — defaults to https://codragraph.vercel.app
  *
  * @param origin - The value of the HTTP `Origin` request header, or `undefined`
  *                 when the header is absent (non-browser request).
  * @returns `true` if the origin is allowed, `false` otherwise.
  */
 export declare const isAllowedOrigin: (origin: string | undefined) => boolean;
+export interface CreateServerOptions {
+    web?: WebDashboardMode;
+}
 type GraphStreamRecord = {
     type: 'node';
     data: GraphNode;
@@ -41,7 +45,15 @@ export declare class ClientDisconnectedError extends Error {
     constructor();
 }
 export declare const isIgnorableGraphQueryError: (err: unknown) => boolean;
+export interface GraphStoreErrorResponse {
+    error: string;
+    code: 'GRAPHSTORE_CORRUPT';
+    operation: string;
+    recovery: string[];
+}
+export declare const isGraphStoreCorruptionError: (err: unknown) => boolean;
+export declare const getGraphStoreErrorResponse: (err: unknown, operation: string) => GraphStoreErrorResponse | null;
 export declare const writeNdjsonRecord: (res: express.Response, record: GraphStreamRecord, signal?: AbortSignal) => Promise<void>;
 export declare const streamGraphNdjson: (res: express.Response, includeContent?: boolean, signal?: AbortSignal) => Promise<void>;
-export declare const createServer: (port: number, host?: string) => Promise<void>;
+export declare const createServer: (port: number, host?: string, options?: CreateServerOptions) => Promise<void>;
 export {};