@papyruslabsai/seshat-mcp 0.16.9 → 0.17.0

package/dist/graph.d.ts

@@ -12,6 +12,12 @@ export interface CallGraph {
     callers: Map<string, Set<string>>;
     callees: Map<string, Set<string>>;
     entityById: Map<string, JstfEntity>;
+    /** Reference-resolution outcomes — honest sparsity as a reported number. */
+    resolutionStats?: {
+        resolved: number;
+        ambiguous: number;
+        unknown: number;
+    };
 }
 export interface BlastRadiusResult {
     affected: string[];
@@ -21,6 +27,12 @@ export interface BlastRadiusResult {
 }
 /**
  * Build a bidirectional call graph from entities' dependency data.
+ *
+ * Reference resolution is identity-honest: a bare-name target resolves to the
+ * unique entity with that local name, or the unique same-file match when the
+ * name is ambiguous repo-wide. A reference that stays ambiguous produces NO
+ * edge — first-wins matching used to silently attribute edges to whichever
+ * same-named entity was indexed first.
  */
 export declare function buildCallGraph(entities: JstfEntity[]): CallGraph;
 /**

package/dist/graph.js

@@ -7,14 +7,34 @@
  * Ancestors = all transitive callers (upstream).
  * Descendants = all transitive callees (downstream).
  */
+/**
+ * Local part of a (possibly file-qualified) entity id.
+ * `src/rooms/participants.js#addParticipant~2` → `addParticipant`.
+ */
+function localIdOf(id) {
+    const i = id.lastIndexOf('#');
+    const local = i === -1 ? id : id.slice(i + 1);
+    return local.replace(/~\d+$/, '');
+}
+function sourceFileOf(entity) {
+    return entity.sourceFile || entity._sourceFile || null;
+}
 /**
  * Build a bidirectional call graph from entities' dependency data.
+ *
+ * Reference resolution is identity-honest: a bare-name target resolves to the
+ * unique entity with that local name, or the unique same-file match when the
+ * name is ambiguous repo-wide. A reference that stays ambiguous produces NO
+ * edge — first-wins matching used to silently attribute edges to whichever
+ * same-named entity was indexed first.
  */
 export function buildCallGraph(entities) {
     const callers = new Map();
     const callees = new Map();
     const entityById = new Map();
     const entityByModule = new Map();
+    const byLocal = new Map(); // local name → entities
+    const bySuffix = new Map(); // last dotted segment of local → entities
     // Index entities
     for (const entity of entities) {
         if (!entity.id)
@@ -22,6 +42,16 @@ export function buildCallGraph(entities) {
         entityById.set(entity.id, entity);
         callers.set(entity.id, new Set());
         callees.set(entity.id, new Set());
+        const local = localIdOf(entity.id);
+        if (!byLocal.has(local))
+            byLocal.set(local, []);
+        byLocal.get(local).push(entity);
+        const suffix = local.includes('.') ? local.split('.').pop() : null;
+        if (suffix) {
+            if (!bySuffix.has(suffix))
+                bySuffix.set(suffix, []);
+            bySuffix.get(suffix).push(entity);
+        }
         if (entity.context?.module) {
             const mod = entity.context.module;
             if (!entityByModule.has(mod))
@@ -29,93 +59,125 @@ export function buildCallGraph(entities) {
             entityByModule.get(mod).push(entity);
         }
     }
-    // Suffix index: map last dotted segment → first matching entity ID (for O(1) suffix lookups)
-    const bySuffix = new Map();
-    for (const [id] of entityById) {
-        const suffix = id.split('.').pop();
-        if (suffix && !bySuffix.has(suffix))
-            bySuffix.set(suffix, id);
+    /** Unique candidate, or unique same-file candidate, else null. */
+    function pick(candidates, contextFile) {
+        if (!candidates || candidates.length === 0)
+            return null;
+        if (candidates.length === 1)
+            return candidates[0];
+        if (contextFile) {
+            const same = candidates.filter(e => sourceFileOf(e) === contextFile);
+            if (same.length === 1)
+                return same[0];
+        }
+        return null;
     }
-    // Filepath index: map source file paths and basenames → entity ID (for O(1) import resolution)
-    const byFilePath = new Map();
-    for (const [id, entity] of entityById) {
-        const src = entity._sourceFile || entity.context?.module || '';
-        if (src) {
-            const basename = src.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
-            if (basename && !byFilePath.has(basename))
-                byFilePath.set(basename, id);
-            if (!byFilePath.has(src))
-                byFilePath.set(src, id);
+    const stats = { resolved: 0, ambiguous: 0, unknown: 0 };
+    /** Resolve a reference string to an entity id, with file context. */
+    function resolveRef(target, contextFile) {
+        const found = (id) => { stats.resolved++; return id; };
+        if (entityById.has(target))
+            return found(target);
+        const direct = pick(byLocal.get(target), contextFile);
+        if (direct)
+            return found(direct.id);
+        if (target.includes('.')) {
+            const dotIdx = target.indexOf('.');
+            const modulePart = target.substring(0, dotIdx);
+            const methodPart = target.substring(dotIdx + 1);
+            const moduleEntities = entityByModule.get(modulePart);
+            if (moduleEntities) {
+                const matches = moduleEntities.filter(e => {
+                    const name = typeof e.struct === 'string' ? e.struct : e.struct?.name;
+                    return localIdOf(e.id) === methodPart || name === methodPart;
+                });
+                const m = pick(matches, contextFile);
+                if (m)
+                    return found(m.id);
+            }
+            const method = pick(byLocal.get(methodPart), contextFile);
+            if (method)
+                return found(method.id);
         }
+        const suffixed = pick(bySuffix.get(target), contextFile);
+        if (suffixed)
+            return found(suffixed.id);
+        const hadCandidates = (byLocal.get(target)?.length || 0) + (bySuffix.get(target)?.length || 0) > 1;
+        if (hadCandidates)
+            stats.ambiguous++;
+        else
+            stats.unknown++;
+        return null;
+    }
+    // File index for import resolution: repo-relative path (sans extension) → entities
+    const byFileBase = new Map();
+    for (const entity of entities) {
+        const f = sourceFileOf(entity);
+        if (!f)
+            continue;
+        const base = f.replace(/\.[^./]+$/, '');
+        if (!byFileBase.has(base))
+            byFileBase.set(base, []);
+        byFileBase.get(base).push(entity);
+    }
+    /** `src/app.js` + `./rooms/participants.js` → `src/rooms/participants` (extensionless). */
+    function resolveRelativeImport(importerFile, source) {
+        const stack = importerFile.split('/').slice(0, -1);
+        for (const part of source.split('/')) {
+            if (part === '.' || part === '')
+                continue;
+            if (part === '..') {
+                if (stack.length === 0)
+                    return null;
+                stack.pop();
+                continue;
+            }
+            stack.push(part);
+        }
+        return stack.join('/').replace(/\.[^./]+$/, '');
     }
     // Build call edges from dependency data
     for (const caller of entities) {
         if (!caller.id || !caller.edges)
             continue;
+        const callerFile = sourceFileOf(caller);
         // Process direct function/method calls
         const callsArray = caller.edges.calls;
         if (Array.isArray(callsArray)) {
             for (const call of callsArray) {
                 if (!call.target)
                     continue;
-                const target = call.target;
-                let calleeId = null;
-                // Strategy 1: Exact match
-                if (entityById.has(target)) {
-                    calleeId = target;
-                }
-                // Strategy 2: Method match (target = "module.method")
-                else if (target.includes('.')) {
-                    const dotIdx = target.indexOf('.');
-                    const modulePart = target.substring(0, dotIdx);
-                    const methodPart = target.substring(dotIdx + 1);
-                    // First try "module.method" as a full entity ID
-                    if (entityById.has(target)) {
-                        calleeId = target;
-                    }
-                    // Search within the module's entities for one named methodPart
-                    if (!calleeId) {
-                        const moduleEntities = entityByModule.get(modulePart);
-                        if (moduleEntities) {
-                            const match = moduleEntities.find(e => {
-                                const name = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-                                return e.id === methodPart || name === methodPart;
-                            });
-                            if (match) {
-                                calleeId = match.id;
-                            }
-                        }
-                    }
-                    // Also try "module.method" concatenated as an ID
-                    if (!calleeId && entityById.has(`${modulePart}.${methodPart}`)) {
-                        calleeId = `${modulePart}.${methodPart}`;
-                    }
-                }
-                // Strategy 3: Suffix match via index (O(1) lookup)
-                if (!calleeId) {
-                    calleeId = bySuffix.get(target) || null;
-                }
+                const calleeId = resolveRef(call.target, callerFile);
                 if (calleeId && calleeId !== caller.id) {
                     callees.get(caller.id)?.add(calleeId);
                     callers.get(calleeId)?.add(caller.id);
                 }
             }
         }
-        // Process lexical imports (wiring file-level dependencies into the graph)
+        // Process lexical imports — resolve the import PATH against the importer's
+        // file, then link each specifier to the same-named entity in the resolved
+        // file. Basename matching used to link any same-named file first-wins.
         const importsArray = caller.edges.imports;
-        if (Array.isArray(importsArray)) {
+        if (Array.isArray(importsArray) && callerFile) {
             for (const imp of importsArray) {
-                // If it's a module-level entity, we link to the module
-                let calleeId = null;
                 const source = imp.source || imp.module;
-                if (!source)
+                if (!source || !source.startsWith('.'))
+                    continue; // package import — no repo entity
+                const resolvedBase = resolveRelativeImport(callerFile, source);
+                if (!resolvedBase)
                     continue;
-                // Attempt to find the imported module or entity via filepath index (O(1) lookup)
-                const sourceBasename = source.split('/').pop()?.replace(/\.[^.]+$/, '') || '';
-                calleeId = byFilePath.get(source) || (sourceBasename ? byFilePath.get(sourceBasename) : null) || null;
-                if (calleeId && calleeId !== caller.id) {
-                    callees.get(caller.id)?.add(calleeId);
-                    callers.get(calleeId)?.add(caller.id);
+                const targetEntities = byFileBase.get(resolvedBase) || byFileBase.get(`${resolvedBase}/index`);
+                if (!targetEntities)
+                    continue;
+                const names = (imp.specifiers || [])
+                    .map((s) => s.imported || s.local)
+                    .filter(Boolean);
+                for (const name of names) {
+                    const match = targetEntities.find(e => localIdOf(e.id) === name);
+                    if (match && match.id !== caller.id) {
+                        callees.get(caller.id)?.add(match.id);
+                        callers.get(match.id)?.add(caller.id);
+                    }
                 }
             }
         }
@@ -123,19 +185,12 @@ export function buildCallGraph(entities) {
         const calledByArray = caller.edges.calledBy;
         if (Array.isArray(calledByArray)) {
             for (const cb of calledByArray) {
-                const source = cb.source;
-                if (!source)
+                if (!cb.source)
                     continue;
-                let callerId = null;
-                if (entityById.has(source)) {
-                    callerId = source;
-                }
-                else {
-                    // Suffix match via index (O(1) lookup)
-                    callerId = bySuffix.get(source) || null;
-                }
-                // In this relationship, the current entity (`caller` in this loop context, despite the name) 
-                // is actually the CALLEE, and the `source` is the true CALLER.
+                // In this relationship, the current entity (`caller` in this loop
+                // context, despite the name) is actually the CALLEE, and the
+                // `source` is the true CALLER.
+                const callerId = resolveRef(cb.source, callerFile);
                 if (callerId && callerId !== caller.id) {
                     callees.get(callerId)?.add(caller.id); // true caller calls this entity
                     callers.get(caller.id)?.add(callerId); // this entity is called by true caller
@@ -143,7 +198,7 @@ export function buildCallGraph(entities) {
             }
         }
     }
-    return { callers, callees, entityById };
+    return { callers, callees, entityById, resolutionStats: stats };
 }
 /**
  * Compute blast radius: all entities affected by changes to the given IDs.

package/dist/index.js

@@ -59,67 +59,67 @@ if (process.argv[2] === 'setup') {
 }
 // ─── Server Instructions ─────────────────────────────────────────
 // Sent to the LLM at connection time. This is the "first contact" pitch.
-const SERVER_INSTRUCTIONS = `Seshat provides structural code analysis backed by a compiled intermediate representation — not heuristic guesses or text search. Every function, class, and route in the synced codebase has been extracted into a typed symbol graph with dependency edges, data flow, constraints, and architectural layer tags. Results are precise and complete — if Seshat says a function has 3 callers, it has exactly 3 callers.
-
-HOW TO USE SESHAT — Seshat tools are designed for iterative exploration, not one-shot lookups. A single tool call answers a single structural question. Understanding a system requires several calls that build on each other — the same way a senior developer investigates code before changing it.
-
-A typical investigation:
-1. query_entities or list_modules → orient yourself in the codebase
-2. get_entity → deep-dive the function you care about
-3. get_blast_radius → discover what's connected and what could break
-4. get_dependencies or get_data_flow → trace specific edges
-5. get_optimal_context → decide what source to read before making changes
-6. Repeat steps 2-5 on newly discovered symbols until you have a complete picture
-
-Each call reveals structure that informs the next. The goal is understanding, not minimum calls. 5-15 queries per investigation is normal and expected.
-
-All tools are read-only and safe to call at any time.
-
-GETTING STARTED — If list_projects returns empty, the current project hasn't been synced yet. Use the sync_project tool to import it:
-1. Detect the git remote: run \`git remote get-url origin\` in the user's terminal
-2. Call sync_project with that repo URL
-3. Wait for extraction to complete (typically 5-30 seconds depending on repo size)
-4. Then call list_projects again — the project will now appear
-Note: For private repos, sync_project will return a GitHub authorization URL. Direct the user to open it in their browser to connect their GitHub account, then retry sync_project.
-
-TOOL REFERENCE — Each tool maps to a structural question:
-
-Setup & Navigation:
-- "What projects are loaded?" → list_projects
-- "Sync this repo to Seshat" → sync_project
-- "How is the codebase organized?" → list_modules
-- "What's the full API surface?" → get_topology
-- "What tier am I on?" → get_account_status
-
-Understanding Code:
-- "Find functions by name or layer" → query_entities
-- "Deep-dive a single function" → get_entity
-- "Who calls this / what does it call?" → get_dependencies
-- "What data does this read/write/mutate?" → get_data_flow
-- "What should I read before modifying X?" → get_optimal_context
-- "Which functions touch the DB / require auth / throw?" → find_by_constraint
-- "What reads or writes the 'users' table?" → find_by_constraint(table="users")
-- "Find functions that can fail, including transitively" → query_traits(trait="fallible")
-
-Change Planning:
-- "What breaks if I change this?" → get_blast_radius
-- "Is there dead code I can safely delete?" → find_dead_code
-- "Is there copy-pasted logic I should consolidate?" → find_semantic_clones
-
-Security & Quality Audits:
-- "Which endpoints require auth and which don't?" → get_auth_matrix
-- "Where is sensitive data exposed without protection?" → find_exposure_leaks
-- "Where are errors thrown but never caught?" → find_error_gaps
-- "Are there architecture violations?" → find_layer_violations
-- "Does framework-agnostic code import framework-specific code?" → find_runtime_violations
-- "Are there memory/lifecycle/ownership issues?" → find_ownership_violations
-
-Metrics:
-- "How coupled is the codebase?" → get_coupling_metrics
-- "Which functions are tested and which aren't?" → get_test_coverage
-
-TEMPORAL ANALYSIS — Any tool accepts an optional temporal parameter: { temporal: { last_n: N } }. This runs the tool across recent snapshots and returns a trend. Requires at least 2 snapshots. Example:
-  get_coupling_metrics({ project: "myapp", temporal: { last_n: 5 } })
+const SERVER_INSTRUCTIONS = `Seshat provides structural code analysis backed by a compiled intermediate representation — not heuristic guesses or text search. Every function, class, and route in the synced codebase has been extracted into a typed symbol graph with dependency edges, data flow, constraints, and architectural layer tags. Results are precise and complete — if Seshat says a function has 3 callers, it has exactly 3 callers.
+
+HOW TO USE SESHAT — Seshat tools are designed for iterative exploration, not one-shot lookups. A single tool call answers a single structural question. Understanding a system requires several calls that build on each other — the same way a senior developer investigates code before changing it.
+
+A typical investigation:
+1. query_entities or list_modules → orient yourself in the codebase
+2. get_entity → deep-dive the function you care about
+3. get_blast_radius → discover what's connected and what could break
+4. get_dependencies or get_data_flow → trace specific edges
+5. get_optimal_context → decide what source to read before making changes
+6. Repeat steps 2-5 on newly discovered symbols until you have a complete picture
+
+Each call reveals structure that informs the next. The goal is understanding, not minimum calls. 5-15 queries per investigation is normal and expected.
+
+All tools are read-only and safe to call at any time.
+
+GETTING STARTED — If list_projects returns empty, the current project hasn't been synced yet. Use the sync_project tool to import it:
+1. Detect the git remote: run \`git remote get-url origin\` in the user's terminal
+2. Call sync_project with that repo URL
+3. Wait for extraction to complete (typically 5-30 seconds depending on repo size)
+4. Then call list_projects again — the project will now appear
+Note: For private repos, sync_project will return a GitHub authorization URL. Direct the user to open it in their browser to connect their GitHub account, then retry sync_project.
+
+TOOL REFERENCE — Each tool maps to a structural question:
+
+Setup & Navigation:
+- "What projects are loaded?" → list_projects
+- "Sync this repo to Seshat" → sync_project
+- "How is the codebase organized?" → list_modules
+- "What's the full API surface?" → get_topology
+- "What tier am I on?" → get_account_status
+
+Understanding Code:
+- "Find functions by name or layer" → query_entities
+- "Deep-dive a single function" → get_entity
+- "Who calls this / what does it call?" → get_dependencies
+- "What data does this read/write/mutate?" → get_data_flow
+- "What should I read before modifying X?" → get_optimal_context
+- "Which functions touch the DB / require auth / throw?" → find_by_constraint
+- "What reads or writes the 'users' table?" → find_by_constraint(table="users")
+- "Find functions that can fail, including transitively" → query_traits(trait="fallible")
+
+Change Planning:
+- "What breaks if I change this?" → get_blast_radius
+- "Is there dead code I can safely delete?" → find_dead_code
+- "Is there copy-pasted logic I should consolidate?" → find_semantic_clones
+
+Security & Quality Audits:
+- "Which endpoints require auth and which don't?" → get_auth_matrix
+- "Where is sensitive data exposed without protection?" → find_exposure_leaks
+- "Where are errors thrown but never caught?" → find_error_gaps
+- "Are there architecture violations?" → find_layer_violations
+- "Does framework-agnostic code import framework-specific code?" → find_runtime_violations
+- "Are there memory/lifecycle/ownership issues?" → find_ownership_violations
+
+Metrics:
+- "How coupled is the codebase?" → get_coupling_metrics
+- "Which functions are tested and which aren't?" → get_test_coverage
+
+TEMPORAL ANALYSIS — Any tool accepts an optional temporal parameter: { temporal: { last_n: N } }. This runs the tool across recent snapshots and returns a trend. Requires at least 2 snapshots. Example:
+  get_coupling_metrics({ project: "myapp", temporal: { last_n: 5 } })
 `;
 // ─── Private Tools (Ptah IP — never exposed publicly) ────────────
 // These tools are reserved for the Ptah write layer. They exist in
@@ -264,6 +264,20 @@ const TOOLS = [
         },
         annotations: READ_ONLY_OPEN,
     },
+    {
+        name: 'get_lineage',
+        title: 'Get Lineage',
+        description: 'The change history of one symbol, typed by what kind of change each commit made (body, calls, data, signature, constraints…), with CI verdicts, reverts, rename tracking, co-change partners, and rejected PRs that touched it. Call before modifying anything load-bearing: it answers "how does this entity usually change, and what happened last time someone tried?" — which no text diff can. Complements get_blast_radius (current impact) with history (past behavior).',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                entity_id: { type: 'string', description: 'Entity ID or name to fetch change history for' },
+            },
+            required: ['entity_id'],
+        },
+        annotations: READ_ONLY_OPEN,
+    },
     {
         name: 'list_modules',
         title: 'List Modules',
@@ -444,7 +458,7 @@ const TOOLS = [
     {
         name: 'simulate_mutation',
         title: 'Simulate Mutation',
-        description: 'Simulate a hypothetical code change without writing anything. Propose adding or removing constraints/traits on a symbol and see which other symbols would break and what fixes they\'d need. Use this to plan a change before making it.',
+        description: 'Simulate a hypothetical code change without writing anything. Five mutation dimensions: constraints/traits (behavioral tags — who upstream breaks), edges (add/remove calls — orphaned callees, inherited error handling and data contracts), data (add/remove table access — which co-tenants of the table must be reviewed), signature (param changes — which call sites break). Use this to plan a change before making it.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -454,12 +468,17 @@ const TOOLS = [
                     type: 'object',
                     description: 'The hypothetical change to apply.',
                     properties: {
-                        dimension: { type: 'string', enum: ['constraints', 'traits'], description: 'The attribute scope to mutate.' },
+                        dimension: { type: 'string', enum: ['constraints', 'traits', 'edges', 'data', 'signature'], description: 'The attribute scope to mutate.' },
                         change: {
                             type: 'object',
                             properties: {
-                                add: { type: 'array', items: { type: 'string' } },
-                                remove: { type: 'array', items: { type: 'string' } },
+                                add: { type: 'array', items: { type: 'string' }, description: 'constraints/traits: tags to add (e.g. "fallible", "auth")' },
+                                remove: { type: 'array', items: { type: 'string' }, description: 'constraints/traits: tags to remove' },
+                                add_calls: { type: 'array', items: { type: 'string' }, description: 'edges: callees the target would start calling' },
+                                remove_calls: { type: 'array', items: { type: 'string' }, description: 'edges: callees the target would stop calling' },
+                                add_tables: { type: 'array', items: { type: 'object', properties: { table: { type: 'string' }, operation: { type: 'string' } } }, description: 'data: tables the target would start touching' },
+                                remove_tables: { type: 'array', items: { type: 'string' }, description: 'data: tables the target would stop touching' },
+                                params: { type: 'object', properties: { add: { type: 'array', items: { type: 'string' } }, remove: { type: 'array', items: { type: 'string' } } }, description: 'signature: parameter changes' },
                             },
                         },
                     },
@@ -588,15 +607,18 @@ function getCloudUrl(path) {
 async function main() {
     const server = new Server({
         name: 'seshat',
-        version: '0.16.6',
+        version: '0.16.10',
     }, {
         capabilities: { tools: {} },
         instructions: SERVER_INSTRUCTIONS,
     });
-    // ─── ListTools — all public tools, Architect tools hidden (Ptah IP) ──
+    // ─── ListTools — all public tools, Architect tools hidden unless Pro mode ──
+    const isProMode = !!process.env.SESHAT_SUPABASE_KEY;
     server.setRequestHandler(ListToolsRequestSchema, async () => {
-        const visibleTools = TOOLS.filter((tool) => !PRIVATE_TOOLS.has(tool.name));
-        process.stderr.write(`[Seshat] ListTools: ${visibleTools.length} tools (${PRIVATE_TOOLS.size} private)\n`);
+        const visibleTools = isProMode
+            ? TOOLS
+            : TOOLS.filter((tool) => !PRIVATE_TOOLS.has(tool.name));
+        process.stderr.write(`[Seshat${isProMode ? ' Pro' : ''}] ListTools: ${visibleTools.length} tools${isProMode ? '' : ` (${PRIVATE_TOOLS.size} private)`}\n`);
         return { tools: visibleTools };
     });
     // ─── CallTool handler ──────────────────────────────────────────
@@ -621,8 +643,8 @@ async function main() {
                 isError: true,
             };
         }
-        // Block private Ptah tools from being called
-        if (PRIVATE_TOOLS.has(name)) {
+        // Block private Ptah tools from being called (unless Pro mode)
+        if (!isProMode && PRIVATE_TOOLS.has(name)) {
             return {
                 content: [{ type: 'text', text: JSON.stringify({ error: `Unknown tool: ${name}` }, null, 2) }],
                 isError: true,
@@ -643,9 +665,9 @@ async function main() {
                     };
                 }
                 const account = await res.json();
-                // List all public tools
+                // List available tools (all tools in Pro mode, public only otherwise)
                 const publicTools = TOOLS
-                    .filter(t => !PRIVATE_TOOLS.has(t.name))
+                    .filter(t => isProMode || !PRIVATE_TOOLS.has(t.name))
                     .map(t => t.name);
                 const response = {
                     status: 'active',
@@ -872,7 +894,7 @@ async function main() {
     });
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    process.stderr.write(`Seshat MCP v0.16.7 connected. Structural intelligence ready.\n`);
+    process.stderr.write(`Seshat MCP v0.16.10 connected. Structural intelligence ready.\n`);
 }
 main().catch((err) => {
     process.stderr.write(`Fatal: ${err.message}\n`);

package/dist/loader.js

@@ -92,13 +92,19 @@ export class BundleLoader {
     getEntityByName(name) {
         return this.getEntities().find(e => {
             const structName = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-            return e.id === name || structName === name;
+            return e.id === name || localIdOfRef(e.id) === name || structName === name;
         });
     }
     isLoaded() {
         return this.loaded;
     }
 }
+/** Local part of a (possibly file-qualified) entity id. */
+function localIdOfRef(id) {
+    const i = id.lastIndexOf('#');
+    const local = i === -1 ? id : id.slice(i + 1);
+    return local.replace(/~\d+$/, '');
+}
 // ─── Multi-Project Loader ─────────────────────────────────────────
 /**
  * Wraps N BundleLoader instances for multi-project access.
@@ -191,7 +197,7 @@ export class MultiLoader {
     getEntityByName(name, project) {
         return this.getEntities(project).find(e => {
             const structName = typeof e.struct === 'string' ? e.struct : e.struct?.name;
-            return e.id === name || structName === name;
+            return e.id === name || localIdOfRef(e.id) === name || structName === name;
         });
     }
     getProjectNames() {

package/dist/tools/dbops.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Database operation extraction from entity coordinates.
+ *
+ * Parses Supabase/Prisma call targets in the edge set and db statements in
+ * the semantics dimension to answer: which tables does this entity read or
+ * write? This is the δ-contract surface that conflict_matrix uses to detect
+ * tasks that collide through shared data even when their symbols and files
+ * are disjoint (the "spawner oscillation" class of conflict).
+ *
+ * Ported from apps/api/routes/mcp.js extractDbOperations so the package's
+ * own tools (conflict_matrix) can use it without the cloud layer.
+ */
+import type { JstfEntity } from '../types.js';
+export interface DbOperation {
+    table: string;
+    operation: string;
+    type: 'db_query' | 'db_mutate';
+}
+export declare function extractDbOps(entity: JstfEntity): DbOperation[];
+/** Aggregate db ops for a set of entities into read/write table sets. */
+export declare function tableContract(entities: JstfEntity[]): {
+    reads: Set<string>;
+    writes: Set<string>;
+};

package/dist/tools/dbops.js

@@ -0,0 +1,78 @@
+/**
+ * Database operation extraction from entity coordinates.
+ *
+ * Parses Supabase/Prisma call targets in the edge set and db statements in
+ * the semantics dimension to answer: which tables does this entity read or
+ * write? This is the δ-contract surface that conflict_matrix uses to detect
+ * tasks that collide through shared data even when their symbols and files
+ * are disjoint (the "spawner oscillation" class of conflict).
+ *
+ * Ported from apps/api/routes/mcp.js extractDbOperations so the package's
+ * own tools (conflict_matrix) can use it without the cloud layer.
+ */
+const WRITE_OPS = new Set(['insert', 'update', 'delete', 'upsert', 'create']);
+export function extractDbOps(entity) {
+    const ops = [];
+    const seen = new Set();
+    const push = (table, operation, isWrite) => {
+        const key = `${table}:${operation}`;
+        if (seen.has(key))
+            return;
+        seen.add(key);
+        ops.push({ table, operation, type: isWrite ? 'db_mutate' : 'db_query' });
+    };
+    const edges = entity.edges;
+    const callees = (edges?.callees || edges?.calls || []);
+    for (const callee of callees) {
+        const target = typeof callee === 'string' ? callee : callee?.target || callee?.id || '';
+        const fromMatch = target.match(/\.from\s*\(\s*['"`](\w+)['"`]\s*\)/);
+        if (fromMatch) {
+            const opMatch = target.match(/\.(insert|update|delete|select|upsert|rpc)\s*\(/);
+            const operation = opMatch ? opMatch[1] : 'query';
+            push(fromMatch[1], operation, WRITE_OPS.has(operation));
+        }
+        const prismaMatch = target.match(/prisma\.(\w+)\.(findMany|findUnique|findFirst|create|update|delete|upsert|count|aggregate)\s*\(/);
+        if (prismaMatch) {
+            push(prismaMatch[1], prismaMatch[2], WRITE_OPS.has(prismaMatch[2]));
+        }
+    }
+    function scanSemantics(stmts) {
+        if (!Array.isArray(stmts))
+            return;
+        for (const stmt of stmts) {
+            if (!stmt || typeof stmt !== 'object')
+                continue;
+            if (stmt.type === 'db_query' || stmt.type === 'db_mutate') {
+                push(String(stmt.model || 'unknown'), String(stmt.operation || 'unknown'), stmt.type === 'db_mutate');
+            }
+            if (stmt.then)
+                scanSemantics(stmt.then);
+            if (stmt.else)
+                scanSemantics(stmt.else);
+            if (stmt.body)
+                scanSemantics(stmt.body);
+            if (stmt.catch?.body)
+                scanSemantics(stmt.catch.body);
+            if (stmt.finally)
+                scanSemantics(stmt.finally);
+        }
+    }
+    scanSemantics(entity.semantics);
+    return ops;
+}
+/** Aggregate db ops for a set of entities into read/write table sets. */
+export function tableContract(entities) {
+    const reads = new Set();
+    const writes = new Set();
+    for (const e of entities) {
+        for (const op of extractDbOps(e)) {
+            if (op.table === 'unknown')
+                continue;
+            if (op.type === 'db_mutate')
+                writes.add(op.table);
+            else
+                reads.add(op.table);
+        }
+    }
+    return { reads, writes };
+}

package/dist/tools/diff.js

@@ -12,6 +12,7 @@ import path from 'path';
 import { bootstrap } from '../bootstrap.js';
 import { computeBlastRadius } from '../graph.js';
 import { getGraph, validateProject, entityName, entityLayer, } from './index.js';
+import { tableContract } from './dbops.js';
 // ─── Entity Identity ─────────────────────────────────────────────
 // Ported from api-v2/translator/seshat-pipeline/src/incremental/diff-engine.mjs
 /**
@@ -260,44 +261,122 @@ export async function diffBundle(args, loader) {
     }
     return result;
 }
+/**
+ * Entropy weights — measured, not asserted. Instance-weighted Shannon entropy
+ * per dimension, FUNCTION-LEVEL entities only (conflict tasks target functions;
+ * import/const entities dilute all-entities numbers). Re-measured 2026-06-11 on
+ * the CLEAN substrate (honest κ, derived χ, collapsed ε — sniffr-backend snap
+ * 205 + ptah snap 207 + second-brain snap 210, ~2,059 JS function instances):
+ * the original 56-project corpus was extracted pre-Testimony-Rule, so part of
+ * its κ entropy was false-positive variety and its χ was path-substring noise.
+ * Clean JS vector: ε .225, Σ .146, δ .140, χ .114, κ .107, σ .089; ρ 0
+ * everywhere. Notable shift vs the corrupted corpus: χ (.087→.114) overtakes
+ * σ (.107→.089) — topology-derived layers carry real discrimination. See
+ * ptah/docs/dimension-entropy-2026-06-clean.json (by_language_functions) and
+ * DIMENSION-ENTROPY-FINDINGS.md (clean re-run section).
+ */
+const CONFLICT_WEIGHTS = {
+    symbols: 0.09, // σ — direct entity overlap
+    epsilon: 0.23, // ε — shared call-graph neighborhood
+    delta: 0.14, // δ — shared data contracts (tables)
+    files: 0.11, // χ-adjacent — shared files
+};
+function jaccard(a, b) {
+    if (a.size === 0 && b.size === 0)
+        return 0;
+    let inter = 0;
+    for (const x of a)
+        if (b.has(x))
+            inter++;
+    return inter / (a.size + b.size - inter);
+}
+function intersect(a, b) {
+    const out = [];
+    for (const x of a)
+        if (b.has(x))
+            out.push(x);
+    return out;
+}
 function classifyConflictTier(taskA, taskB) {
-    // Check symbol overlap → Tier 3 (MUST sequence)
-    const sharedEntities = [];
-    for (const id of taskA.entityIds) {
-        if (taskB.entityIds.has(id)) {
-            sharedEntities.push(id);
+    const sharedEntities = intersect(taskA.entityIds, taskB.entityIds);
+    const sharedFiles = intersect(taskA.files, taskB.files);
+    const sharedNeighbors = intersect(taskA.neighbors, taskB.neighbors);
+    // δ-contract overlap with read/write direction per side
+    const sharedTables = [];
+    const allTables = new Set([
+        ...taskA.tablesRead, ...taskA.tablesWritten,
+        ...taskB.tablesRead, ...taskB.tablesWritten,
+    ]);
+    for (const table of allTables) {
+        const aW = taskA.tablesWritten.has(table);
+        const aR = taskA.tablesRead.has(table) || aW;
+        const bW = taskB.tablesWritten.has(table);
+        const bR = taskB.tablesRead.has(table) || bW;
+        if (aR && bR && (aW || bW)) {
+            // overlap matters only when at least one side writes
+            sharedTables.push({ table, taskA: aW ? 'write' : 'read', taskB: bW ? 'write' : 'read' });
         }
     }
+    const writeWrite = sharedTables.filter(t => t.taskA === 'write' && t.taskB === 'write');
+    const readWrite = sharedTables.filter(t => t.taskA !== t.taskB);
+    // Entropy-weighted evidence score in [0,1]
+    const tablesA = new Set([...taskA.tablesRead, ...taskA.tablesWritten]);
+    const tablesB = new Set([...taskB.tablesRead, ...taskB.tablesWritten]);
+    const w = CONFLICT_WEIGHTS;
+    const totalW = w.symbols + w.epsilon + w.delta + w.files;
+    const conflictScore = Math.round(((w.symbols * jaccard(taskA.entityIds, taskB.entityIds) +
+        w.epsilon * jaccard(taskA.neighbors, taskB.neighbors) +
+        w.delta * jaccard(tablesA, tablesB) +
+        w.files * jaccard(taskA.files, taskB.files)) / totalW) * 1000) / 1000;
+    const base = { conflictScore, sharedFiles, sharedEntities, sharedTables, sharedNeighbors };
+    // Tier 3 — must sequence
     if (sharedEntities.length > 0) {
         return {
+            ...base,
             tier: 3,
             reason: `${sharedEntities.length} shared symbols — MUST sequence to maintain surgical splice integrity`,
-            sharedFiles: [],
-            sharedEntities,
         };
     }
-    // Check file overlap → Tier 1 or 2
-    const sharedFiles = [];
-    for (const file of taskA.files) {
-        if (taskB.files.has(file)) {
-            sharedFiles.push(file);
-        }
+    if (writeWrite.length > 0) {
+        return {
+            ...base,
+            tier: 3,
+            reason: `shared data contract — both tasks WRITE table(s) ${writeWrite.map(t => t.table).join(', ')}; ` +
+                'symbols are disjoint but the tasks collide through the data layer — MUST sequence',
+        };
+    }
+    // Tier 2 — parallelize with care
+    if (readWrite.length > 0) {
+        return {
+            ...base,
+            tier: 2,
+            reason: `read/write data contract overlap on table(s) ${readWrite.map(t => t.table).join(', ')} — ` +
+                'parallel-safe only if the reader tolerates the writer\'s changes',
+        };
+    }
+    if (sharedFiles.length > 0) {
+        return {
+            ...base,
+            tier: 2,
+            reason: `${sharedFiles.length} shared files but different symbols — safe to parallelize via surgical splicing`,
+        };
+    }
+    if (sharedNeighbors.length > 0) {
+        return {
+            ...base,
+            tier: 2,
+            reason: `call-graph adjacency — tasks touch ${sharedNeighbors.length} shared neighbor(s) within 1 hop ` +
+                `(e.g. ${sharedNeighbors.slice(0, 3).join(', ')}) — review the shared interface before parallelizing`,
+        };
     }
-    if (sharedFiles.length === 0) {
+    if (conflictScore > 0) {
         return {
+            ...base,
             tier: 1,
-            reason: 'No shared files — safe to parallelize',
-            sharedFiles: [],
-            sharedEntities: [],
+            reason: 'No conflicting overlap (weak affinity only — shared read-only tables or nearby code) — safe to parallelize',
         };
     }
-    // Same file, different symbols → Tier 2 (Safe via Surgical Splicer)
-    return {
-        tier: 2,
-        reason: `${sharedFiles.length} shared files but different symbols — safe to parallelize via surgical splicing`,
-        sharedFiles,
-        sharedEntities: [],
-    };
+    return { ...base, tier: 1, reason: 'No shared symbols, files, data contracts, or call-graph adjacency — safe to parallelize' };
 }
 // ─── Execution Plan Builder ───────────────────────────────────────
 /**
@@ -376,6 +455,7 @@ export function conflictMatrix(args, loader) {
     const warnings = [];
     // Resolve entity sets for each task
     const resolvedTasks = [];
+    const graph = getGraph(args.project, loader);
     for (const task of tasks) {
         const entityIds = new Set();
         const files = new Set();
@@ -400,12 +480,11 @@ export function conflictMatrix(args, loader) {
         }
         // Expand blast radius if requested
         if (task.expand_blast_radius && entityIds.size > 0) {
-            const g = getGraph(args.project, loader);
-            const blastResult = computeBlastRadius(g, entityIds);
+            const blastResult = computeBlastRadius(graph, entityIds);
             for (const affectedId of blastResult.affected) {
                 if (!entityIds.has(affectedId)) {
                     entityIds.add(affectedId);
-                    const affectedEntity = g.entityById.get(affectedId);
+                    const affectedEntity = graph.entityById.get(affectedId);
                     if (affectedEntity) {
                         entities.push(affectedEntity);
                         if (affectedEntity._sourceFile)
@@ -414,7 +493,20 @@ export function conflictMatrix(args, loader) {
                 }
             }
         }
-        resolvedTasks.push({ id: task.id, entityIds, files, entities, dimensions });
+        // δ-contract surface: tables read/written by the task's entities
+        const { reads: tablesRead, writes: tablesWritten } = tableContract(entities);
+        // ε surface: 1-hop call-graph neighborhood (always computed — cheap, and
+        // it catches adjacent-task conflicts even without blast-radius expansion)
+        const neighbors = new Set();
+        for (const id of entityIds) {
+            for (const c of graph.callers.get(id) || [])
+                if (!entityIds.has(c))
+                    neighbors.add(c);
+            for (const c of graph.callees.get(id) || [])
+                if (!entityIds.has(c))
+                    neighbors.add(c);
+        }
+        resolvedTasks.push({ id: task.id, entityIds, files, entities, dimensions, tablesRead, tablesWritten, neighbors });
     }
     // Pairwise comparison
     const matrix = [];
@@ -429,11 +521,16 @@ export function conflictMatrix(args, loader) {
                 taskB: taskB.id,
                 tier: result.tier,
                 reason: result.reason,
+                conflictScore: result.conflictScore,
             };
             if (result.sharedFiles.length > 0)
                 entry.sharedFiles = result.sharedFiles;
             if (result.sharedEntities.length > 0)
                 entry.sharedEntities = result.sharedEntities;
+            if (result.sharedTables.length > 0)
+                entry.sharedTables = result.sharedTables;
+            if (result.sharedNeighbors.length > 0)
+                entry.sharedNeighbors = result.sharedNeighbors.slice(0, 10);
             matrix.push(entry);
             if (result.tier === 3) {
                 tier3Edges.push([taskA.id, taskB.id]);

package/dist/tools/functors.d.ts

@@ -81,10 +81,21 @@ export declare function query_traits(args: {
 export declare function simulate_mutation(args: {
     entity_id: string;
     mutation: {
-        dimension: 'constraints' | 'traits';
+        dimension: 'constraints' | 'traits' | 'edges' | 'data' | 'signature';
         change: {
             add?: string[];
             remove?: string[];
+            add_calls?: string[];
+            remove_calls?: string[];
+            add_tables?: Array<{
+                table: string;
+                operation?: string;
+            }>;
+            remove_tables?: string[];
+            params?: {
+                add?: string[];
+                remove?: string[];
+            };
         };
     };
     project?: string;

package/dist/tools/functors.js

@@ -9,6 +9,7 @@ import path from 'path';
 import { computeBlastRadius } from '../graph.js';
 import { getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
 import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, } from '../supabase.js';
+import { extractDbOps } from './dbops.js';
 // ─── Layer ordering for violation detection ──────────────────────
 const LAYER_ORDER = {
     route: 0,
@@ -984,6 +985,19 @@ export function simulate_mutation(args, loader) {
     }
     const targetId = targetEntity.id;
     const { dimension, change } = args.mutation;
+    // Structural-dimension projections. Logic (body) changes are deliberately
+    // not simulated statement-level: an edit to the body manifests structurally
+    // as call-edge and data-contract deltas, so simulating those IS simulating
+    // the body at the resolution the graph supports.
+    if (dimension === 'edges') {
+        return simulateEdgeMutation(targetEntity, change, g, args.mutation, loader, args.project);
+    }
+    if (dimension === 'data') {
+        return simulateDataMutation(targetEntity, change, g, args.mutation);
+    }
+    if (dimension === 'signature') {
+        return simulateSignatureMutation(targetEntity, change, g, args.mutation);
+    }
     const addedTags = (change.add || []).map(t => t.toLowerCase());
     // We are currently simulating topological fallout for newly ADDED constraints/traits.
     // Example: If we add "fallible" or "auth", who upstream breaks because they don't handle it?
@@ -1051,6 +1065,176 @@ export function simulate_mutation(args, loader) {
         fallout,
     };
 }
+/** ε: adding/removing call edges — orphan detection + inherited contracts/fallibility. */
+function simulateEdgeMutation(target, change, g, mutation, loader, project) {
+    const fallout = [];
+    const contractsAdded = [];
+    const contractsDropped = [];
+    const orphanCandidates = [];
+    const notFound = [];
+    const resolve = (nameOrId) => g.entityById.get(nameOrId)
+        || (loader.getEntityById(nameOrId, project) ?? loader.getEntityByName(nameOrId, project) ?? undefined);
+    for (const removed of change.remove_calls || []) {
+        const callee = resolve(removed);
+        if (!callee) {
+            notFound.push(removed);
+            continue;
+        }
+        // Orphan check: is the target the callee's ONLY in-graph caller?
+        const callers = g.callers.get(callee.id) || new Set();
+        const otherCallers = [...callers].filter(c => c !== target.id);
+        if (otherCallers.length === 0) {
+            orphanCandidates.push(callee.id);
+            fallout.push({
+                entity: entitySummary(callee),
+                distance: 1,
+                reason: `${entityName(target)} is its only caller — removing the call orphans it (dead-code candidate).`,
+                requiredFix: `Delete ${callee.id} as well, or confirm a dynamic/runtime caller exists.`,
+            });
+        }
+        // Contracts the target loses transitive access to via this callee
+        for (const op of extractDbOps(callee)) {
+            contractsDropped.push({ table: op.table, operation: op.operation, via: callee.id });
+        }
+    }
+    for (const added of change.add_calls || []) {
+        const callee = resolve(added);
+        if (!callee) {
+            notFound.push(added);
+            continue;
+        }
+        // Inherited fallibility: caller must handle what the new callee can throw
+        const calleeConstraints = callee.constraints;
+        const calleeTraits = callee.traits;
+        const calleeThrows = !!(calleeConstraints?.throws || calleeTraits?.self?.fallible);
+        const targetConstraints = target.constraints;
+        const targetCatches = !!(targetConstraints?.errorHandling
+            && (targetConstraints.errorHandling.tryCatch
+                || targetConstraints.errorHandling.catchClause
+                || targetConstraints.errorHandling.catches));
+        if (calleeThrows && !targetCatches) {
+            fallout.push({
+                entity: entitySummary(target),
+                distance: 0,
+                reason: `New callee ${callee.id} can throw; ${entityName(target)} has no error handling.`,
+                requiredFix: `Wrap the new call in try/catch or propagate (and re-check ${entityName(target)}'s callers).`,
+            });
+        }
+        // Inherited data contracts: the target's δ surface grows
+        for (const op of extractDbOps(callee)) {
+            contractsAdded.push({ table: op.table, operation: op.operation, via: callee.id });
+        }
+    }
+    const result = {
+        target: entitySummary(target),
+        mutation,
+        affectedSymbolsCount: fallout.length,
+        fallout,
+        _summary: `Edge mutation on ${entityName(target)}: ${(change.add_calls || []).length} call(s) added, ` +
+            `${(change.remove_calls || []).length} removed → ${orphanCandidates.length} orphan candidate(s), ` +
+            `${contractsAdded.length} contract(s) inherited, ${contractsDropped.length} dropped.`,
+    };
+    if (contractsAdded.length > 0)
+        result.contractsAdded = contractsAdded;
+    if (contractsDropped.length > 0)
+        result.contractsDropped = contractsDropped;
+    if (orphanCandidates.length > 0)
+        result.orphanCandidates = orphanCandidates;
+    if (notFound.length > 0)
+        result.notFound = notFound;
+    return result;
+}
+/** δ: changing the target's table contract — who else shares that surface. */
+function simulateDataMutation(target, change, g, mutation) {
+    const fallout = [];
+    // Index every entity's table contract once
+    const coTenants = new Map();
+    for (const [, entity] of g.entityById) {
+        if (entity.id === target.id)
+            continue;
+        for (const op of extractDbOps(entity)) {
+            if (!coTenants.has(op.table))
+                coTenants.set(op.table, []);
+            coTenants.get(op.table).push({ entity, writes: op.type === 'db_mutate' });
+        }
+    }
+    const WRITE_OPS = new Set(['insert', 'update', 'delete', 'upsert', 'create']);
+    for (const { table, operation } of change.add_tables || []) {
+        const isWrite = WRITE_OPS.has((operation || 'query').toLowerCase());
+        const tenants = coTenants.get(table) || [];
+        const seen = new Set();
+        for (const { entity, writes } of tenants) {
+            if (seen.has(entity.id))
+                continue;
+            seen.add(entity.id);
+            // a new WRITE conflicts with everyone on the table; a new READ conflicts with writers
+            if (isWrite || writes) {
+                fallout.push({
+                    entity: entitySummary(entity),
+                    distance: 1,
+                    reason: `Shares the '${table}' contract (${writes ? 'writes' : 'reads'} it) — ` +
+                        `${entityName(target)} would now ${isWrite ? 'write' : 'read'} the same table.`,
+                    requiredFix: isWrite && writes
+                        ? `Sequence changes with ${entity.id} or establish row/column ownership on '${table}'.`
+                        : `Verify ${entity.id} tolerates the new ${isWrite ? 'writes' : 'read dependency'} on '${table}'.`,
+                });
+            }
+        }
+    }
+    for (const table of change.remove_tables || []) {
+        const tenants = coTenants.get(table) || [];
+        const seen = new Set();
+        for (const { entity } of tenants) {
+            if (seen.has(entity.id))
+                continue;
+            seen.add(entity.id);
+            fallout.push({
+                entity: entitySummary(entity),
+                distance: 1,
+                reason: `Remaining tenant of '${table}' after ${entityName(target)} exits the contract.`,
+                requiredFix: `Confirm ${entity.id} does not depend on rows/state ${entityName(target)} was maintaining in '${table}'.`,
+            });
+        }
+    }
+    return {
+        target: entitySummary(target),
+        mutation,
+        affectedSymbolsCount: fallout.length,
+        fallout,
+        _summary: `Data-contract mutation on ${entityName(target)}: ${fallout.length} co-tenant(s) of the affected table(s) to review.`,
+    };
+}
+/** σ signature: every direct caller's call site breaks. */
+function simulateSignatureMutation(target, change, g, mutation) {
+    const fallout = [];
+    const callers = g.callers.get(target.id) || new Set();
+    const added = change.params?.add || [];
+    const removed = change.params?.remove || [];
+    const desc = [
+        added.length > 0 ? `+${added.join(', +')}` : null,
+        removed.length > 0 ? `-${removed.join(', -')}` : null,
+    ].filter(Boolean).join(' ');
+    for (const callerId of callers) {
+        const caller = g.entityById.get(callerId);
+        if (!caller)
+            continue;
+        fallout.push({
+            entity: entitySummary(caller),
+            distance: 1,
+            reason: `Direct caller — call site breaks when the signature changes (${desc || 'params modified'}).`,
+            requiredFix: `Update the call to ${entityName(target)} in ${caller._sourceFile || callerId}.`,
+        });
+    }
+    const exported = typeof target.struct !== 'string' && !!target.struct?.exported;
+    return {
+        target: entitySummary(target),
+        mutation,
+        affectedSymbolsCount: fallout.length,
+        fallout,
+        ...(exported ? { warning: 'Target is exported — external/dynamic callers outside this graph may also break.' } : {}),
+        _summary: `Signature mutation on ${entityName(target)} (${desc || 'params'}): ${fallout.length} direct call site(s) must be updated.`,
+    };
+}
 // ─── Tool: query_data_targets (Data Flow Analysis) ──────────────
 export function query_data_targets(args, loader) {
     const projErr = validateProject(args.project, loader);

package/dist/tools/index.d.ts

@@ -9,6 +9,7 @@
  */
 import type { JstfEntity, ProjectLoader } from '../types.js';
 import { type CallGraph } from '../graph.js';
+export { extractDbOps, tableContract, type DbOperation } from './dbops.js';
 export declare function getGraph(project: string | undefined, loader: ProjectLoader): CallGraph;
 /**
  * Validate project param. Returns error string if invalid, null if OK.

package/dist/tools/index.js

@@ -8,6 +8,7 @@
  * `project` parameter. In multi-project mode, `project` is required.
  */
 import { buildCallGraph, computeBlastRadius } from '../graph.js';
+export { extractDbOps, tableContract } from './dbops.js';
 export function getGraph(project, loader) {
     // Fast path: use pre-computed call graph edges cached on the snapshot row
     // (avoids 3-10s CPU rebuild on first request for large codebases)
@@ -80,6 +81,7 @@ export function entitySummary(e) {
         layer: entityLayer(e),
         module: e.context?.module || null,
         sourceFile: e._sourceFile || null,
+        line: e._sourceLine ?? undefined,
         sourceLanguage: e._sourceLanguage || null,
         async: typeof e.struct !== 'string' ? e.struct?.async : undefined,
         exported: typeof e.struct !== 'string' ? e.struct?.exported : undefined,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.16.9",
+  "version": "0.17.0",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {