brainclaw 1.23.0 → 1.25.0

package/dist/commands/code-map.js

@@ -1,12 +1,12 @@
 /**
  * `brainclaw code-map <subcommand>` — CLI surface over the Code Map backend
  * (spec §9). Mirrors plan-resource.ts: a switch over the subcommand delegating
- * to a JsonlBackend (status | refresh | find | brief). The backend owns all
+ * to a JsonlBackend (status | refresh | find | brief | impact | export | outline). The backend owns
  * query logic; this file only adapts it to argv + stdout (text or --json), and
  * every output carries the freshness_badge.
  */
 import { JsonlBackend } from '../core/code-map/backend.js';
-const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief']);
+const KNOWN_SUBCOMMANDS = new Set(['status', 'refresh', 'find', 'brief', 'impact', 'export', 'outline']);
 function backend() {
     return new JsonlBackend();
 }
@@ -57,6 +57,49 @@ export async function runCodeMap(subcommand, args, options = {}) {
         printBrief(result, options);
         return;
     }
+    if (normalized === 'impact') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map impact requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map impact <symbol-or-path> [--depth 2]');
+            process.exit(1);
+        }
+        const result = await be.impact({ target, depth: options.depth, limit: options.limit, cwd });
+        printImpact(result, options);
+        return;
+    }
+    if (normalized === 'export') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map export requires <symbol-or-path>.');
+            console.error('  Usage: brainclaw code-map export <symbol-or-path> [--direction both] [--depth 1] [--max-nodes 100] [--max-edges 200]');
+            process.exit(1);
+        }
+        const result = await be.exportGraph({
+            target,
+            targetKind: options.targetKind,
+            direction: options.direction,
+            depth: options.depth,
+            maxNodes: options.maxNodes,
+            maxEdges: options.maxEdges,
+            minConfidence: options.minConfidence,
+            format: options.format,
+            cwd,
+        });
+        printExport(result, options);
+        return;
+    }
+    if (normalized === 'outline') {
+        const target = args.join(' ').trim();
+        if (!target) {
+            console.error('Error: code-map outline requires <file>.');
+            console.error('  Usage: brainclaw code-map outline <file>');
+            process.exit(1);
+        }
+        const result = await be.outline({ path: target, limit: options.limit, cwd });
+        printOutline(result, options);
+        return;
+    }
     console.error(`Error: unknown code-map subcommand "${subcommand}".`);
     console.error(`  Available: ${[...KNOWN_SUBCOMMANDS].join(', ')}`);
     process.exit(1);
@@ -144,4 +187,78 @@ function printBrief(result, options) {
         }
     }
 }
+function printImpact(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    const cause = (row) => row.causes.map((item) => `${item.kind}${item.module ? ` ${item.module}` : ''}${item.source_line ? `:${item.source_line}` : ''}`).join(', ');
+    console.log(`Code Map impact: "${result.target}"`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    console.log(`  Definition: ${result.definition.entries.length} (${result.definition.match_kind})`);
+    for (const entry of result.definition.entries)
+        console.log(`    ${entry.name} — ${entry.path}`);
+    console.log(`  Direct dependents: ${result.direct_dependents.length}${result.limits.direct_truncated ? '+' : ''}`);
+    for (const dependent of result.direct_dependents)
+        console.log(`    ${dependent.path} — ${cause(dependent)}`);
+    if (result.limits.max_depth > 1) {
+        console.log(`  Transitive dependents: ${result.transitive_dependents.length}${result.limits.transitive_truncated ? '+' : ''}`);
+        for (const dependent of result.transitive_dependents)
+            console.log(`    [depth ${dependent.depth}] ${dependent.path} — ${cause(dependent)}`);
+    }
+    console.log(`  Tests: ${result.risk.counters.resolved_test_files} resolved, ${result.risk.counters.suggested_test_files} naming suggestion(s)`);
+    for (const test of result.tests_for)
+        console.log(`    [${test.relation}, confidence=${test.confidence}] ${test.path} — ${test.reason}`);
+    console.log(`  Risk: ${result.risk.score} (${result.risk.formula}; direct=${result.risk.counters.direct_dependents}, transitive=${result.risk.counters.transitive_dependents})`);
+}
+function printExport(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map export: "${result.target}" (${result.target_kind})`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    console.log(`  Roots: ${result.root_node_ids.length}; nodes=${result.nodes.length}/${result.limits.max_nodes}; edges=${result.edges.length}/${result.limits.max_edges}; depth=${result.limits.max_depth}; direction=${result.limits.direction}; min-confidence=${result.limits.min_confidence}`);
+    const truncation = Object.entries(result.truncated).filter(([, value]) => value).map(([key]) => key);
+    if (truncation.length > 0)
+        console.log(`  Truncated: ${truncation.join(', ')}`);
+    if (result.format === 'mermaid' && result.mermaid) {
+        console.log(result.mermaid);
+        return;
+    }
+    for (const edge of result.edges) {
+        const source = edge.source ? ` @ ${edge.source.path}${edge.source.line === null || edge.source.line === undefined ? '' : `:${edge.source.line}`}` : '';
+        console.log(`  ${edge.from} -[${edge.kind}, confidence=${edge.confidence}${source}]-> ${edge.to}`);
+    }
+}
+function printOutline(result, options) {
+    if (options.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    console.log(`Code Map outline: "${result.path}"`);
+    console.log(`  Index:    ${result.index_status}`);
+    console.log(`  ${badgeLine(result.freshness_badge)}`);
+    if (!result.file_indexed) {
+        console.log('  Symbols:  (file not indexed)');
+        return;
+    }
+    console.log(`  Parse:    ${result.parse_status}`);
+    if (result.symbols.length === 0) {
+        console.log('  Symbols:  (none)');
+    }
+    else {
+        for (const symbol of result.symbols) {
+            const subtype = symbol.subtype ? ` ${symbol.subtype}` : '';
+            const span = symbol.span ? `${symbol.span.start_line}:${symbol.span.start_col}` : 'unknown';
+            const exported = symbol.exported ? ' export' : '';
+            console.log(`  [${span}] ${symbol.kind}${subtype} ${symbol.name}${exported} confidence=${symbol.confidence}`);
+        }
+    }
+    if (result.truncated)
+        console.log(`  … ${result.symbol_count - result.symbols.length} more indexed symbol(s)`);
+    if (result.diagnostics.length > 0) {
+        console.log(`  Diagnostics: ${result.diagnostics.length}${result.diagnostics_truncated ? '+' : ''}`);
+    }
+}
 //# sourceMappingURL=code-map.js.map

package/dist/commands/mcp-catalog.js

@@ -409,6 +409,52 @@ export const MCP_READ_TOOLS = [
             required: ['target'],
         },
     },
+    {
+        name: 'bclaw_code_impact',
+        description: 'Explain a symbol or source file\'s local blast radius from existing resolved imports: definition, direct dependents with edge causes, optional bounded transitives, affected test files, low-confidence naming suggestions kept separate, and a count-based risk score. Read-only; never refreshes.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or source-file path whose impact to inspect.' },
+                depth: { type: 'number', description: 'Maximum graph depth. 1 (default) returns direct dependents only; 2+ opts into transitives. Clamped to 4.' },
+                limit: { type: 'number', description: 'Maximum rows in each dependent section and in naming suggestions. Clamped to 100.' },
+            },
+            required: ['target'],
+        },
+    },
+    {
+        name: 'bclaw_code_export',
+        description: 'Export a compact, deterministic, confidence-filtered local Code Map subgraph around one symbol or file. Requires a target; defaults to one hop and hard caps nodes (100), edges (200), and depth (4), so it never exports a whole graph. JSON retains every edge kind, source, and confidence. format="mermaid" adds a projection of the same JSON nodes/edges. Read-only; never refreshes or calls an external service.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                target: { type: 'string', description: 'Symbol name or source-file path around which to export a local subgraph.' },
+                targetKind: { type: 'string', enum: ['symbol', 'file'], description: 'Optional explicit target kind; otherwise a source path is detected safely.' },
+                direction: { type: 'string', enum: ['outgoing', 'incoming', 'both'], description: 'Which edge direction(s) to follow. Default: both.' },
+                depth: { type: 'number', description: 'Maximum graph distance from the root(s). Default 1; clamped to 0..4.' },
+                maxNodes: { type: 'number', description: 'Maximum nodes returned. Default 100; hard-capped at 100.' },
+                maxEdges: { type: 'number', description: 'Maximum edges returned. Default 200; hard-capped at 200.' },
+                minConfidence: { type: 'number', description: 'Persisted confidence threshold for nodes and relationships. Default/minimum 0.5.' },
+                format: { type: 'string', enum: ['json', 'mermaid'], description: 'Default json; mermaid adds a projection derived from the same bounded graph.' },
+            },
+            required: ['target'],
+        },
+    },
+    {
+        name: 'bclaw_code_outline',
+        description: 'Return a bounded source-ordered outline for one indexed file: symbol name, kind, subtype, span, exported flag, and persisted confidence. Read-only: it reads the existing file shard only, never parses or refreshes. `index_status` distinguishes a missing index, a file not indexed, and an indexed file with zero symbols.',
+        annotations: { tier: 'standard', category: 'discovery', headlessApproval: 'auto' },
+        inputSchema: {
+            type: 'object',
+            properties: {
+                path: { type: 'string', description: 'Workspace-relative source file path (for example `src/app/App.tsx`).' },
+                limit: { type: 'number', description: 'Maximum symbols to return; clamped to the hard cap of 200.' },
+            },
+            required: ['path'],
+        },
+    },
 ];
 const MCP_WRITE_TOOLS = [
     {

package/dist/commands/mcp.js

@@ -1089,8 +1089,8 @@ async function _executeMcpToolCallInner(payload) {
         }
         // Code Map tools (spec §9). These delegate to the async JsonlBackend, so
         // they are handled here rather than via the synchronous read-tool path.
-        // status/find/brief are reads; refresh is a write (prompt approval).
-        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_refresh') {
+        // status/find/brief/impact/export/outline are reads; refresh is a write (prompt approval).
+        if (name === 'bclaw_code_status' || name === 'bclaw_code_find' || name === 'bclaw_code_brief' || name === 'bclaw_code_impact' || name === 'bclaw_code_export' || name === 'bclaw_code_outline' || name === 'bclaw_code_refresh') {
             const { JsonlBackend } = await import('../core/code-map/backend.js');
             const be = new JsonlBackend();
             if (name === 'bclaw_code_status') {
@@ -1127,6 +1127,58 @@ async function _executeMcpToolCallInner(payload) {
                     }),
                 };
             }
+            // bclaw_code_export
+            if (name === 'bclaw_code_export') {
+                const target = typeof args.target === 'string' ? args.target : '';
+                if (!target.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_export requires a non-empty target.') };
+                }
+                const targetKind = args.targetKind === 'symbol' || args.targetKind === 'file' ? args.targetKind : undefined;
+                const direction = args.direction === 'outgoing' || args.direction === 'incoming' || args.direction === 'both' ? args.direction : undefined;
+                const depth = typeof args.depth === 'number' ? args.depth : undefined;
+                const maxNodes = typeof args.maxNodes === 'number' ? args.maxNodes : undefined;
+                const maxEdges = typeof args.maxEdges === 'number' ? args.maxEdges : undefined;
+                const minConfidence = typeof args.minConfidence === 'number' ? args.minConfidence : undefined;
+                const format = args.format === 'mermaid' ? 'mermaid' : args.format === 'json' ? 'json' : undefined;
+                const result = await be.exportGraph({ target, targetKind, direction, depth, maxNodes, maxEdges, minConfidence, format, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map export "${result.target}": ${result.nodes.length} node(s), ${result.edges.length} edge(s), depth=${result.limits.max_depth}, freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_impact
+            if (name === 'bclaw_code_impact') {
+                const target = typeof args.target === 'string' ? args.target : '';
+                if (!target.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_impact requires a non-empty target.') };
+                }
+                const depth = typeof args.depth === 'number' ? args.depth : undefined;
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.impact({ target, depth, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map impact "${result.target}": ${result.risk.counters.direct_dependents} direct, ${result.risk.counters.transitive_dependents} transitive dependent(s), risk=${result.risk.score}, freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
+            // bclaw_code_outline
+            if (name === 'bclaw_code_outline') {
+                const outlinePath = typeof args.path === 'string' ? args.path : '';
+                if (!outlinePath.trim()) {
+                    return { response: createToolErrorResponse('validation_error', 'bclaw_code_outline requires a non-empty path.') };
+                }
+                const limit = typeof args.limit === 'number' ? args.limit : undefined;
+                const result = await be.outline({ path: outlinePath, limit, cwd });
+                return {
+                    response: toolResponse({
+                        content: [{ type: 'text', text: `Code Map outline "${result.path}": ${result.symbols.length}/${result.symbol_count} symbol(s), index=${result.index_status}, freshness=${result.freshness_badge.status}` }],
+                        structuredContent: { ...result, freshness_badge: result.freshness_badge },
+                    }),
+                };
+            }
             // bclaw_code_brief
             const target = typeof args.target === 'string' ? args.target : '';
             if (!target.trim()) {

package/dist/core/code-map/backend.js

@@ -10,21 +10,70 @@
  */
 import { execFileSync } from 'node:child_process';
 import path from 'node:path';
-import { readManifest, storeExists } from './store.js';
+import { readManifest, readShard, storeExists } from './store.js';
 import { refresh as runRefresh } from './refresh.js';
 import { applyGitHeadDrift, withCoarse } from './freshness.js';
 import { brief as runBrief, find as runFind } from './query.js';
+import { impact as runImpact } from './impact.js';
+import { exportSubgraph } from './export.js';
+import { fileId } from './ids.js';
 import { resolveTraversal, aggregateFind, aggregateBrief } from './aggregate.js';
 import { defaultMemoryReader } from './memory-reader.js';
 import { listNestedProjects, refreshWorkspaceCascade } from './cascade.js';
 import { loadConfig } from '../config.js';
 /** spec §9 caps the brief reading list at 12 files. */
 export const BRIEF_FILE_CAP = 12;
+/**
+ * Agent-facing file outline (P2b). The symbol count is deliberately bounded:
+ * an outline is a navigation aid, not a replacement for opening a generated
+ * source file. `symbol_count` always records the complete indexed count.
+ */
+export const OUTLINE_SYMBOL_CAP = 200;
+/** Diagnostics are useful context, but unbounded provider facts are not. */
+export const OUTLINE_DIAGNOSTIC_CAP = 20;
 function badge(status, details = {}) {
     // pln#601 — stamp the coarse rollup at construction so every backend-built badge
     // (status, missing_index fallbacks, find/brief base) carries it uniformly.
     return withCoarse({ status, details });
 }
+/**
+ * Convert a user path into the POSIX project-relative identity used by shards.
+ * This is pure path arithmetic: outline must not stat, parse, or otherwise touch
+ * the live source file on its read path.
+ */
+function normalizeOutlinePath(requestedPath, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, requestedPath);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+        return null;
+    }
+    return relative.replace(/\\/g, '/');
+}
+function outlineLimit(limit) {
+    if (limit === undefined || !Number.isFinite(limit))
+        return OUTLINE_SYMBOL_CAP;
+    return Math.min(Math.max(Math.floor(limit), 0), OUTLINE_SYMBOL_CAP);
+}
+function compareOutlineSymbols(a, b) {
+    // Symbols normally always have spans. Keep malformed/legacy span-less nodes
+    // deterministic and at the end instead of trusting shard append order.
+    const as = a.span;
+    const bs = b.span;
+    if (as && bs) {
+        return as.start_line - bs.start_line
+            || as.start_col - bs.start_col
+            || as.end_line - bs.end_line
+            || as.end_col - bs.end_col
+            || a.name.localeCompare(b.name)
+            || a.node_id.localeCompare(b.node_id);
+    }
+    if (as)
+        return -1;
+    if (bs)
+        return 1;
+    return a.name.localeCompare(b.name) || a.node_id.localeCompare(b.node_id);
+}
 /**
  * Read the working tree's current commit at `root` (read-path git-HEAD drift,
  * trp_42688015). Returns null on any failure or a non-git project (also detached
@@ -244,6 +293,114 @@ export class JsonlBackend {
             freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
         };
     }
+    /**
+     * Explain a target's resolved blast radius. Unlike brief(), this deliberately
+     * stays store-local: impact only traverses persisted P1c/P1d edges and reports
+     * their concrete causes, with an opt-in bounded transitive walk.
+     */
+    async impact(input) {
+        const ctx = this.queryContext(input);
+        const out = runImpact(input.target, { depth: input.depth, limit: input.limit }, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
+        return {
+            ...out,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Export only a caller-selected, hard-bounded local graph. This stays
+     * store-local even at a multi-project root: implicit workspace graph dumps
+     * are intentionally unsupported.
+     */
+    async exportGraph(input) {
+        const ctx = this.queryContext(input);
+        const out = exportSubgraph(input.target, input, ctx);
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const base = badge(out.freshness_badge.status, out.freshness_badge.details);
+        return {
+            ...out,
+            freshness_badge: this.withHeadDrift(base, manifest, input.cwd),
+        };
+    }
+    /**
+     * Return an indexed file's symbols in source order. This reads exactly one
+     * manifest and one deterministic shard; it never calls refresh, extractor, or
+     * the lazy live-file validator, so the response is a snapshot of the index.
+     */
+    async outline(input) {
+        const cwd = input.cwd ?? process.cwd();
+        const manifest = readManifest(input.cwd, input.preferredDirName);
+        const root = manifest?.project_root ?? cwd;
+        const normalizedPath = normalizeOutlinePath(input.path.trim(), root) ?? input.path.trim().replace(/\\/g, '/');
+        const missing = () => ({
+            path: normalizedPath,
+            index_status: 'missing_index',
+            file_indexed: false,
+            parse_status: null,
+            symbol_count: 0,
+            symbols: [],
+            truncated: false,
+            diagnostics: [],
+            diagnostics_truncated: false,
+            freshness_badge: badge('missing_index', { hint: 'run refresh' }),
+        });
+        if (!manifest || manifest.freshness.status === 'missing_index')
+            return missing();
+        const freshnessBadge = this.withHeadDrift(badge(manifest.freshness.status, {
+            stale_file_count: manifest.freshness.stale_file_count,
+            partial_reason: manifest.freshness.partial_reason,
+        }), manifest, input.cwd);
+        const safePath = normalizeOutlinePath(input.path.trim(), root);
+        if (!safePath) {
+            return {
+                ...missing(),
+                index_status: 'file_not_indexed',
+                freshness_badge: freshnessBadge,
+            };
+        }
+        const shard = readShard(fileId(manifest.project_id, safePath), input.cwd, input.preferredDirName);
+        if (!shard || shard.path !== safePath) {
+            return {
+                path: safePath,
+                index_status: 'file_not_indexed',
+                file_indexed: false,
+                parse_status: null,
+                symbol_count: 0,
+                symbols: [],
+                truncated: false,
+                diagnostics: [],
+                diagnostics_truncated: false,
+                freshness_badge: freshnessBadge,
+            };
+        }
+        const allSymbols = shard.nodes
+            .filter((node) => node.kind === 'symbol')
+            .map((node) => ({
+            node_id: node.id,
+            name: node.name,
+            kind: node.kind,
+            subtype: node.subtype ?? null,
+            span: node.span ?? null,
+            exported: node.exported,
+            confidence: node.confidence,
+        }))
+            .sort(compareOutlineSymbols);
+        const limit = outlineLimit(input.limit);
+        const diagnostics = shard.diagnostics.slice(0, OUTLINE_DIAGNOSTIC_CAP);
+        return {
+            path: safePath,
+            index_status: 'indexed',
+            file_indexed: true,
+            parse_status: shard.parse_status,
+            symbol_count: allSymbols.length,
+            symbols: allSymbols.slice(0, limit).map(({ node_id: _nodeId, ...symbol }) => symbol),
+            truncated: allSymbols.length > limit,
+            diagnostics,
+            diagnostics_truncated: shard.diagnostics.length > diagnostics.length,
+            freshness_badge: freshnessBadge,
+        };
+    }
     /**
      * Annotate a read badge with git-HEAD drift vs the commit the index was built
      * against (`manifest.git.head`). trp_42688015 — a branch switch (whole-tree move)

package/dist/core/code-map/export.js

@@ -0,0 +1,212 @@
+/**
+ * Bounded Code Map subgraph export. Mermaid is rendered from this module's JSON
+ * model; it never takes a second, potentially different graph traversal.
+ */
+import path from 'node:path';
+import { withCoarse } from './freshness.js';
+import { listShards, readManifest } from './store.js';
+/** Absolute traversal and response ceilings: a whole-graph export is impossible. */
+export const CODE_EXPORT_MAX_DEPTH = 4;
+export const CODE_EXPORT_NODE_CAP = 100;
+export const CODE_EXPORT_EDGE_CAP = 200;
+/** Low-confidence extracted data is never included by default or opt-out. */
+export const CODE_EXPORT_MIN_CONFIDENCE = 0.5;
+function clampInteger(value, fallback, min, max) {
+    if (value === undefined || !Number.isFinite(value))
+        return fallback;
+    return Math.min(Math.max(Math.floor(value), min), max);
+}
+function clampConfidence(value) {
+    if (value === undefined || !Number.isFinite(value))
+        return CODE_EXPORT_MIN_CONFIDENCE;
+    return Math.min(Math.max(value, CODE_EXPORT_MIN_CONFIDENCE), 1);
+}
+function normalizePath(value) {
+    return value.replace(/\\/g, '/');
+}
+function normalizeDirection(value) {
+    return value === 'outgoing' || value === 'incoming' || value === 'both' ? value : 'both';
+}
+function normalizeFormat(value) {
+    return value === 'mermaid' || value === 'json' ? value : 'json';
+}
+function normalizeTargetKind(value, target) {
+    return value === 'symbol' || value === 'file' ? value : inferTargetKind(target);
+}
+function inferTargetKind(target) {
+    return /[\\/]/.test(target)
+        || /\.(?:[cm]?[jt]sx?|py|php|java|go|rs|cs|rb|c|cc|cpp|cxx|h|hpp)$/i.test(target)
+        ? 'file'
+        : 'symbol';
+}
+/** No selector may address the project root itself or escape it. */
+function normalizeFileTarget(target, projectRoot) {
+    const root = path.resolve(projectRoot);
+    const absolute = path.resolve(root, target);
+    const relative = path.relative(root, absolute);
+    if (!relative || relative === '.' || relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative))
+        return null;
+    return normalizePath(relative);
+}
+function compareNodes(a, b) {
+    const as = a.span;
+    const bs = b.span;
+    return a.path.localeCompare(b.path)
+        || (as?.start_line ?? -1) - (bs?.start_line ?? -1)
+        || (as?.start_col ?? -1) - (bs?.start_col ?? -1)
+        || a.kind.localeCompare(b.kind)
+        || a.name.localeCompare(b.name)
+        || a.id.localeCompare(b.id);
+}
+function compareEdges(a, b) {
+    return a.from.localeCompare(b.from)
+        || a.to.localeCompare(b.to)
+        || a.kind.localeCompare(b.kind)
+        || (a.source?.path ?? '').localeCompare(b.source?.path ?? '')
+        || (a.source?.line ?? -1) - (b.source?.line ?? -1)
+        || a.id.localeCompare(b.id);
+}
+function graphNode(node) {
+    return { id: node.id, kind: node.kind, subtype: node.subtype ?? null, lang: node.lang, name: node.name, path: node.path,
+        span: node.span ?? null, exported: node.exported, confidence: node.confidence };
+}
+function graphEdge(edge) {
+    return { id: edge.id, from: edge.from, to: edge.to, kind: edge.kind, confidence: edge.confidence, source: edge.source ?? null };
+}
+function matchesRoot(node, target, targetKind, normalizedPath) {
+    return targetKind === 'file'
+        ? node.kind === 'file' && normalizedPath !== null && normalizePath(node.path) === normalizedPath
+        : node.kind === 'symbol' && node.name === target;
+}
+function usableEdge(edge, nodes, minConfidence) {
+    return edge.confidence >= minConfidence
+        && (nodes.get(edge.from)?.confidence ?? -Infinity) >= minConfidence
+        && (nodes.get(edge.to)?.confidence ?? -Infinity) >= minConfidence;
+}
+function touches(edge, nodeId, direction) {
+    return ((direction === 'outgoing' || direction === 'both') && edge.from === nodeId)
+        || ((direction === 'incoming' || direction === 'both') && edge.to === nodeId);
+}
+function neighbor(edge, nodeId) {
+    return edge.from === nodeId ? edge.to : edge.from;
+}
+function emptyOutput(target, targetKind, limits, freshness, format) {
+    const graph = {
+        target, target_kind: targetKind, root_node_ids: [], nodes: [], edges: [], limits,
+        truncated: { roots: false, nodes: false, edges: false, depth: false }, freshness_badge: freshness,
+    };
+    return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };
+}
+/**
+ * Select a deterministic, confidence-filtered neighborhood from persisted shards.
+ * No refresh, parse, inference, service call, or unbounded response occurs here.
+ */
+export function exportSubgraph(targetInput, options, ctx) {
+    const target = targetInput.trim();
+    const targetKind = normalizeTargetKind(options?.targetKind, target);
+    const format = normalizeFormat(options?.format);
+    const limits = {
+        direction: normalizeDirection(options?.direction),
+        max_depth: clampInteger(options?.depth, 1, 0, CODE_EXPORT_MAX_DEPTH),
+        max_nodes: clampInteger(options?.maxNodes, CODE_EXPORT_NODE_CAP, 1, CODE_EXPORT_NODE_CAP),
+        max_edges: clampInteger(options?.maxEdges, CODE_EXPORT_EDGE_CAP, 0, CODE_EXPORT_EDGE_CAP),
+        min_confidence: clampConfidence(options?.minConfidence),
+    };
+    const manifest = readManifest(ctx.cwd, ctx.preferredDirName);
+    const missing = withCoarse({ status: 'missing_index', details: { hint: 'run refresh' } });
+    if (!manifest || manifest.freshness.status === 'missing_index' || !target)
+        return emptyOutput(target, targetKind, limits, missing, format);
+    const targetPath = targetKind === 'file' ? normalizeFileTarget(target, manifest.project_root) : null;
+    if (targetKind === 'file' && !targetPath) {
+        return emptyOutput(target, targetKind, limits, withCoarse({
+            status: manifest.freshness.status, details: { invalid_target: 'file path must be inside the indexed project' },
+        }), format);
+    }
+    const allNodes = new Map();
+    const allEdges = new Map();
+    for (const shard of listShards(ctx.cwd, ctx.preferredDirName).sort((a, b) => a.path.localeCompare(b.path) || a.file_id.localeCompare(b.file_id))) {
+        for (const node of shard.nodes)
+            if (!allNodes.has(node.id))
+                allNodes.set(node.id, node);
+        for (const edge of shard.edges)
+            if (!allEdges.has(edge.id))
+                allEdges.set(edge.id, edge);
+    }
+    const nodes = new Map([...allNodes.entries()].filter(([, node]) => node.confidence >= limits.min_confidence));
+    const edges = [...allEdges.values()].filter((edge) => usableEdge(edge, nodes, limits.min_confidence)).sort(compareEdges);
+    const roots = [...nodes.values()].filter((node) => matchesRoot(node, target, targetKind, targetPath)).sort(compareNodes);
+    const selected = new Set();
+    const rootNodeIds = [];
+    let rootsTruncated = false;
+    for (const root of roots) {
+        if (selected.size >= limits.max_nodes) {
+            rootsTruncated = true;
+            break;
+        }
+        selected.add(root.id);
+        rootNodeIds.push(root.id);
+    }
+    const selectedEdges = new Map();
+    const visited = new Set(rootNodeIds);
+    let nodesTruncated = false;
+    let edgesTruncated = false;
+    let depthTruncated = false;
+    let frontier = [...rootNodeIds];
+    for (let currentDepth = 0; frontier.length > 0; currentDepth++) {
+        const next = new Set();
+        frontier.sort((a, b) => compareNodes(nodes.get(a), nodes.get(b)));
+        for (const nodeId of frontier) {
+            const incident = edges.filter((edge) => touches(edge, nodeId, limits.direction));
+            if (currentDepth >= limits.max_depth) {
+                if (incident.some((edge) => !selectedEdges.has(edge.id)))
+                    depthTruncated = true;
+                continue;
+            }
+            for (const edge of incident) {
+                const adjacent = neighbor(edge, nodeId);
+                if (!selected.has(adjacent) && selected.size >= limits.max_nodes) {
+                    nodesTruncated = true;
+                    continue;
+                }
+                if (selectedEdges.size >= limits.max_edges && !selectedEdges.has(edge.id)) {
+                    edgesTruncated = true;
+                    continue;
+                }
+                selected.add(adjacent);
+                selectedEdges.set(edge.id, edge);
+                if (!visited.has(adjacent)) {
+                    visited.add(adjacent);
+                    next.add(adjacent);
+                }
+            }
+        }
+        frontier = [...next];
+    }
+    const graph = {
+        target, target_kind: targetKind, root_node_ids: rootNodeIds,
+        nodes: [...selected].map((id) => nodes.get(id)).filter((node) => node !== undefined).sort(compareNodes).map(graphNode),
+        edges: [...selectedEdges.values()].sort(compareEdges).map(graphEdge),
+        limits, truncated: { roots: rootsTruncated, nodes: nodesTruncated, edges: edgesTruncated, depth: depthTruncated },
+        freshness_badge: withCoarse({ status: manifest.freshness.status,
+            details: { stale_file_count: manifest.freshness.stale_file_count, partial_reason: manifest.freshness.partial_reason } }),
+    };
+    return format === 'mermaid' ? { ...graph, format, mermaid: toMermaid(graph) } : { ...graph, format };
+}
+function mermaidLabel(node) {
+    return JSON.stringify(`${node.name} (${node.kind})`.replace(/[\r\n]/g, ' '));
+}
+/** Deterministic textual projection of a graph already selected by exportSubgraph. */
+export function toMermaid(graph) {
+    const ids = new Map(graph.nodes.map((node, index) => [node.id, `n${index}`]));
+    const lines = ['flowchart TD'];
+    for (const node of graph.nodes)
+        lines.push(`  ${ids.get(node.id)}[${mermaidLabel(node)}]`);
+    for (const edge of graph.edges) {
+        const from = ids.get(edge.from);
+        const to = ids.get(edge.to);
+        if (from && to)
+            lines.push(`  ${from} -->|${edge.kind} · ${edge.confidence}| ${to}`);
+    }
+    return lines.join('\n');
+}
+//# sourceMappingURL=export.js.map