@papyruslabsai/seshat-mcp 0.4.2 → 0.7.0

package/dist/graph.js

@@ -31,59 +31,111 @@ export function buildCallGraph(entities) {
     }
     // Build call edges from dependency data
     for (const caller of entities) {
-        if (!caller.id || !caller.edges?.calls)
+        if (!caller.id || !caller.edges)
             continue;
+        // Process direct function/method calls
         const callsArray = caller.edges.calls;
-        if (!Array.isArray(callsArray))
-            continue;
-        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 (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;
                 }
-                // Search within the module's entities for one named methodPart
+                // 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: Prefix match
                 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;
+                    for (const [id] of entityById) {
+                        if (id.endsWith(`.${target}`) || id === target) {
+                            calleeId = id;
+                            break;
                         }
                     }
                 }
-                // Also try "module.method" concatenated as an ID
-                if (!calleeId && entityById.has(`${modulePart}.${methodPart}`)) {
-                    calleeId = `${modulePart}.${methodPart}`;
+                if (calleeId && calleeId !== caller.id) {
+                    callees.get(caller.id)?.add(calleeId);
+                    callers.get(calleeId)?.add(caller.id);
                 }
             }
-            // Strategy 3: Prefix match
-            if (!calleeId) {
-                for (const [id] of entityById) {
-                    if (id.endsWith(`.${target}`) || id === target) {
+        }
+        // Process lexical imports (wiring file-level dependencies into the graph)
+        const importsArray = caller.edges.imports;
+        if (Array.isArray(importsArray)) {
+            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)
+                    continue;
+                // Attempt to find the imported module or entity
+                // Here we do a basic substring match against source files/modules
+                for (const [id, entity] of entityById) {
+                    const eSource = entity._sourceFile || entity.context?.module || '';
+                    if (eSource && (eSource.includes(source) || source.includes(eSource))) {
                         calleeId = id;
                         break;
                     }
                 }
+                if (calleeId && calleeId !== caller.id) {
+                    callees.get(caller.id)?.add(calleeId);
+                    callers.get(calleeId)?.add(caller.id);
+                }
             }
-            if (calleeId && calleeId !== caller.id) {
-                callees.get(caller.id)?.add(calleeId);
-                callers.get(calleeId)?.add(caller.id);
+        }
+        // Process IoC / Dynamic Dispatch (calledBy)
+        const calledByArray = caller.edges.calledBy;
+        if (Array.isArray(calledByArray)) {
+            for (const cb of calledByArray) {
+                const source = cb.source;
+                if (!source)
+                    continue;
+                let callerId = null;
+                if (entityById.has(source)) {
+                    callerId = source;
+                }
+                else {
+                    for (const [id] of entityById) {
+                        if (id.endsWith(`.${source}`) || id === source) {
+                            callerId = id;
+                            break;
+                        }
+                    }
+                }
+                // 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.
+                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
+                }
             }
         }
     }

package/dist/index.d.ts

@@ -13,12 +13,13 @@
  * Single-project mode (default):
  *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
  *
- * 18 tools across 3 categories:
+ * 20 tools across 4 categories:
  *   Discovery:  list_projects, query_entities, get_entity, list_modules, get_topology
  *   Graph:      get_dependencies, get_data_flow, find_by_constraint, get_blast_radius
  *   Analysis:   find_dead_code, find_layer_violations, get_coupling_metrics,
  *               get_auth_matrix, find_error_gaps, get_test_coverage,
  *               get_optimal_context, estimate_task_cost, report_actual_burn
+ *   Diff:       diff_bundle, conflict_matrix
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)

package/dist/index.js

@@ -13,12 +13,13 @@
  * Single-project mode (default):
  *   When SESHAT_PROJECTS is not set, loads from CWD. No `project` param needed.
  *
- * 18 tools across 3 categories:
+ * 20 tools across 4 categories:
  *   Discovery:  list_projects, query_entities, get_entity, list_modules, get_topology
  *   Graph:      get_dependencies, get_data_flow, find_by_constraint, get_blast_radius
  *   Analysis:   find_dead_code, find_layer_violations, get_coupling_metrics,
  *               get_auth_matrix, find_error_gaps, get_test_coverage,
  *               get_optimal_context, estimate_task_cost, report_actual_burn
+ *   Diff:       diff_bundle, conflict_matrix
  *
  * Usage:
  *   npx @papyruslabs/seshat-mcp                           # single project (CWD)
@@ -33,7 +34,8 @@ import { CallToolRequestSchema, ListToolsRequestSchema, } from '@modelcontextpro
 import { MultiLoader } from './loader.js';
 import { bootstrap } from './bootstrap.js';
 import { initTools, queryEntities, getEntity, getDependencies, getDataFlow, findByConstraint, getBlastRadius, listModules, getTopology, } from './tools/index.js';
-import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, reportActualBurn, } from './tools/functors.js';
+import { findDeadCode, findLayerViolations, getCouplingMetrics, getAuthMatrix, findErrorGaps, getTestCoverage, getOptimalContext, estimateTaskCost, reportActualBurn, find_runtime_violations, find_ownership_violations, query_traits, simulate_mutation, query_data_targets, find_exposure_leaks, find_semantic_clones, } from './tools/functors.js';
+import { diffBundle, conflictMatrix, } from './tools/diff.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
  * Discover project directories from SESHAT_PROJECTS env var.
@@ -386,6 +388,170 @@ const TOOLS = [
             },
         },
     },
+    // ─── Semantic (9D) JSTF-T Tools ─────────────────────────────────
+    {
+        name: 'find_runtime_violations',
+        description: 'Analyze the call graph across the ρ (Runtime) dimension. Finds architectural leaks where framework-agnostic code improperly imports framework-specific code (e.g. pure logic calling React hooks) or where incompatible frameworks mix directly.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+    },
+    {
+        name: 'find_ownership_violations',
+        description: 'Analyze the codebase across the λ (Ownership/Lifetimes) dimension. Flags entities with complex memory management constraints, unsafe blocks, escaping boundaries, or illegal mutability patterns on borrowed references.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+    },
+    {
+        name: 'query_traits',
+        description: 'Search the codebase across the τ (Traits/Capabilities) dimension. Allows you to find entities by their abstract capabilities (e.g., "fallible", "asyncContext", "generator") regardless of their structural syntax.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                trait: {
+                    type: 'string',
+                    description: 'The trait or capability to search for (e.g., "fallible", "asyncContext")',
+                },
+            },
+            required: ['trait'],
+        },
+    },
+    {
+        name: 'simulate_mutation',
+        description: 'The Semantic Physics Engine. Proposes a hypothetical change to an entity\'s dimensions (like adding a "fallible" or "auth" trait) and simulates the topological fallout upstream and downstream. Returns a blueprint of exactly which other entities will break and what fixes they require.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                entity_id: {
+                    type: 'string',
+                    description: 'The target entity to mutate.',
+                },
+                mutation: {
+                    type: 'object',
+                    description: 'The hypothetical change to apply.',
+                    properties: {
+                        dimension: { type: 'string', enum: ['constraints', 'traits'] },
+                        change: {
+                            type: 'object',
+                            properties: {
+                                add: { type: 'array', items: { type: 'string' } },
+                                remove: { type: 'array', items: { type: 'string' } },
+                            },
+                        },
+                    },
+                    required: ['dimension', 'change'],
+                },
+            },
+            required: ['entity_id', 'mutation'],
+        },
+    },
+    {
+        name: 'query_data_targets',
+        description: 'Search the codebase across the δ (Data) dimension to find all entities that read or write to a specific database table, state object, or data source. This acts as a reverse-index for data flow, essential for planning migrations or state refactors.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                target_name: {
+                    type: 'string',
+                    description: 'The name of the database table, state object, or data source to query (e.g., "users", "auth_token").',
+                },
+            },
+            required: ['target_name'],
+        },
+    },
+    {
+        name: 'find_exposure_leaks',
+        description: 'Analyze the call graph across the χ (Context) dimension to find architectural visibility leaks. Flags paths where a "public" or "api" entity directly accesses a "private" entity, potentially leaking sensitive data or bypassing internal service boundaries.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+            },
+        },
+    },
+    {
+        name: 'find_semantic_clones',
+        description: 'Analyze the codebase across the Σ (Semantics) dimension to find duplicated logic blocks. Normalizes variables and compares abstract syntax tree shapes to identify identical algorithms written across different files or even different languages.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                min_complexity: {
+                    type: 'number',
+                    description: 'Minimum number of logic expressions required to constitute a match (default: 5).',
+                },
+            },
+        },
+    },
+    // ─── Diff Tools ─────────────────────────────────────────────────
+    {
+        name: 'diff_bundle',
+        description: 'Compare entities between a worktree and the loaded project. Shows which entities were added, removed, or modified at the symbol level — not a line diff, but a structural diff showing changed signatures, call graphs, constraints, and logic. Extracts the worktree automatically if no bundle exists.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                worktree_path: {
+                    type: 'string',
+                    description: 'Absolute path to the worktree or branch checkout to compare against the loaded project',
+                },
+                include_unchanged: {
+                    type: 'boolean',
+                    description: 'Include unchanged entities in the output (default: false)',
+                },
+            },
+            required: ['worktree_path'],
+        },
+    },
+    {
+        name: 'conflict_matrix',
+        description: 'Given multiple tasks, classify every task pair into conflict tiers bridging JSTF-T theory and Git reality. Tier 1 (different files, safe), Tier 2 (same file, different entities, safe), Tier 3 (same entity, orthogonal Spatial Zones like imports vs logic, risky but parallelizable), Tier 4 (same entity, same Spatial Zone, MUST sequence). Passing "dimensions" per task enables Tier 3 downgrades.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                tasks: {
+                    type: 'array',
+                    items: {
+                        type: 'object',
+                        properties: {
+                            id: {
+                                type: 'string',
+                                description: 'Unique task identifier (e.g. "add-dark-mode")',
+                            },
+                            entity_ids: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Entity IDs or names that this task will modify',
+                            },
+                            dimensions: {
+                                type: 'array',
+                                items: { type: 'string' },
+                                description: 'Optional: JSTF-T dimensions this task will modify (e.g., "edges", "struct", "semantics", "constraints"). Used to downgrade conflicts via Spatial Zones.',
+                            },
+                            expand_blast_radius: {
+                                type: 'boolean',
+                                description: 'Include transitively affected entities in the conflict check (default: false)',
+                            },
+                        },
+                        required: ['id', 'entity_ids'],
+                    },
+                    description: 'Array of tasks to check for conflicts. Each task specifies which entities it will modify.',
+                },
+            },
+            required: ['tasks'],
+        },
+    },
 ];
 // ─── Server Setup ─────────────────────────────────────────────────
 async function main() {
@@ -441,7 +607,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.4.2',
+        version: '0.5.0',
     }, {
         capabilities: {
             tools: {},
@@ -531,6 +697,35 @@ async function main() {
                 case 'report_actual_burn':
                     result = await reportActualBurn(args);
                     break;
+                // Semantic (9D) JSTF-T Tools
+                case 'find_runtime_violations':
+                    result = find_runtime_violations(args);
+                    break;
+                case 'find_ownership_violations':
+                    result = find_ownership_violations(args);
+                    break;
+                case 'query_traits':
+                    result = query_traits(args);
+                    break;
+                case 'simulate_mutation':
+                    result = simulate_mutation(args);
+                    break;
+                case 'query_data_targets':
+                    result = query_data_targets(args);
+                    break;
+                case 'find_exposure_leaks':
+                    result = find_exposure_leaks(args);
+                    break;
+                case 'find_semantic_clones':
+                    result = find_semantic_clones(args);
+                    break;
+                // Diff Tools
+                case 'diff_bundle':
+                    result = await diffBundle(args);
+                    break;
+                case 'conflict_matrix':
+                    result = conflictMatrix(args);
+                    break;
                 default:
                     result = { error: `Unknown tool: ${name}` };
             }

package/dist/tools/diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Cross-Bundle Analysis Tools: diff_bundle + conflict_matrix
+ *
+ * diff_bundle: Compare entities between a worktree and the loaded project.
+ * conflict_matrix: Classify conflict tiers for parallel task scheduling.
+ *
+ * These tools compare TWO entity sets (base vs branch, or task vs task),
+ * unlike the single-bundle queries in index.ts and functors.ts.
+ */
+export declare function diffBundle(args: {
+    worktree_path: string;
+    project?: string;
+    include_unchanged?: boolean;
+}): Promise<unknown>;
+export declare function conflictMatrix(args: {
+    tasks: Array<{
+        id: string;
+        entity_ids: string[];
+        dimensions?: string[];
+        expand_blast_radius?: boolean;
+    }>;
+    project?: string;
+}): unknown;

package/dist/tools/diff.js

@@ -0,0 +1,491 @@
+/**
+ * Cross-Bundle Analysis Tools: diff_bundle + conflict_matrix
+ *
+ * diff_bundle: Compare entities between a worktree and the loaded project.
+ * conflict_matrix: Classify conflict tiers for parallel task scheduling.
+ *
+ * These tools compare TWO entity sets (base vs branch, or task vs task),
+ * unlike the single-bundle queries in index.ts and functors.ts.
+ */
+import fs from 'fs';
+import path from 'path';
+import { bootstrap } from '../bootstrap.js';
+import { computeBlastRadius } from '../graph.js';
+import { getLoader, getGraph, validateProject, entityName, entityLayer, } from './index.js';
+// ─── Entity Identity ─────────────────────────────────────────────
+// Ported from api-v2/translator/seshat-pipeline/src/incremental/diff-engine.mjs
+/**
+ * Generate a unique key for an entity: <relative_path>::<id>
+ *
+ * Uses _sourceFile (already relative in bundles) or derives from
+ * sourceFile (absolute path) by stripping the repo root.
+ */
+function entityKey(entity, repoRoot) {
+    let relativePath = entity._sourceFile || null;
+    // If _sourceFile not set, try deriving from sourceFile (absolute)
+    if (!relativePath) {
+        const raw = entity;
+        const sourceFile = (raw.sourceFile || '').replace(/\\/g, '/');
+        if (repoRoot && sourceFile) {
+            const normalizedRoot = repoRoot.replace(/\\/g, '/').replace(/\/+$/, '') + '/';
+            if (sourceFile.startsWith(normalizedRoot)) {
+                relativePath = sourceFile.substring(normalizedRoot.length);
+            }
+            else {
+                // Case-insensitive match (Windows paths)
+                const lowerFile = sourceFile.toLowerCase();
+                const lowerRoot = normalizedRoot.toLowerCase();
+                if (lowerFile.startsWith(lowerRoot)) {
+                    relativePath = sourceFile.substring(normalizedRoot.length);
+                }
+            }
+        }
+        if (!relativePath) {
+            relativePath = sourceFile || 'unknown';
+        }
+    }
+    // Normalize path separators
+    relativePath = (relativePath || 'unknown').replace(/\\/g, '/');
+    const id = entity.id || (typeof entity.struct === 'string' ? entity.struct : entity.struct?.name) || 'anonymous';
+    return `${relativePath}::${id}`;
+}
+// ─── Bundle Loading ───────────────────────────────────────────────
+/**
+ * Load a branch bundle from a worktree path.
+ * Does NOT add to the global MultiLoader — this is a transient comparison target.
+ *
+ * 1. Check <worktree_path>/.seshat/_bundle.json — parse if exists
+ * 2. If not, run bootstrap() to extract on-the-fly
+ * 3. Apply the same field remapping as BundleLoader (sourceFile → _sourceFile, etc.)
+ */
+async function loadBranchBundle(worktreePath) {
+    const absPath = path.resolve(worktreePath);
+    const bundlePath = path.join(absPath, '.seshat', '_bundle.json');
+    let bundle;
+    if (fs.existsSync(bundlePath)) {
+        const raw = fs.readFileSync(bundlePath, 'utf-8');
+        bundle = JSON.parse(raw);
+    }
+    else {
+        // Auto-extract via bootstrap
+        const result = await bootstrap(absPath);
+        if (!result.success) {
+            throw new Error(`Failed to extract bundle from ${absPath}: ${result.error}`);
+        }
+        // Read the freshly generated bundle
+        if (!fs.existsSync(bundlePath)) {
+            throw new Error(`Bootstrap succeeded but no bundle found at ${bundlePath}`);
+        }
+        const raw = fs.readFileSync(bundlePath, 'utf-8');
+        bundle = JSON.parse(raw);
+    }
+    const entities = bundle.entities || [];
+    // Apply the same field remapping as BundleLoader.load()
+    for (const e of entities) {
+        const raw = e;
+        if (raw.sourceFile && !e._sourceFile) {
+            e._sourceFile = raw.sourceFile;
+        }
+        if (raw.sourceLanguage && !e._sourceLanguage) {
+            e._sourceLanguage = raw.sourceLanguage;
+        }
+    }
+    // Try to get commit SHA from manifest
+    let commitSha = '';
+    const manifestPath = path.join(absPath, '.seshat', 'manifest.json');
+    if (fs.existsSync(manifestPath)) {
+        try {
+            const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf-8'));
+            commitSha = manifest.commitSha || '';
+        }
+        catch { /* ignore */ }
+    }
+    return {
+        entities,
+        source: bundle.source || absPath,
+        commitSha,
+        entityCount: entities.length,
+    };
+}
+// ─── Field Comparison ─────────────────────────────────────────────
+/** The entity fields to compare, mapped to user-facing names (v0.4.2 convention) */
+const FIELD_MAP = [
+    ['struct', 'structure'],
+    ['edges', 'call_graph'],
+    ['data', 'data_flow'],
+    ['constraints', 'constraints'],
+    ['context', 'context'],
+    ['ownership', 'ownership'],
+    ['traits', 'type_info'],
+    ['runtime', 'runtime'],
+    ['semantics', 'logic'],
+];
+/**
+ * Compare two entities field-by-field. Returns which fields changed
+ * using user-facing names.
+ */
+function compareEntityFields(baseEntity, branchEntity) {
+    const changed = [];
+    for (const [field, displayName] of FIELD_MAP) {
+        const baseVal = baseEntity[field];
+        const branchVal = branchEntity[field];
+        // Both undefined/null → no change
+        if (baseVal == null && branchVal == null)
+            continue;
+        // One null, other not → changed
+        if (baseVal == null || branchVal == null) {
+            changed.push(displayName);
+            continue;
+        }
+        // Deep compare via JSON
+        if (JSON.stringify(baseVal) !== JSON.stringify(branchVal)) {
+            changed.push(displayName);
+        }
+    }
+    return changed;
+}
+// ─── Tool: diff_bundle ───────────────────────────────────────────
+export async function diffBundle(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const baseEntities = loader.getEntities(args.project);
+    const baseManifest = loader.getManifest(args.project);
+    if (baseEntities.length === 0) {
+        return { error: 'No base entities loaded. Ensure the project has been extracted.' };
+    }
+    // Load branch bundle
+    let branchData;
+    try {
+        branchData = await loadBranchBundle(args.worktree_path);
+    }
+    catch (err) {
+        return { error: `Failed to load branch bundle: ${err.message}` };
+    }
+    const branchEntities = branchData.entities;
+    // Build entity maps by key
+    const baseSource = baseManifest?.commitSha ? '' : ''; // base entities have relative paths already
+    const baseMap = new Map();
+    for (const entity of baseEntities) {
+        const key = entityKey(entity);
+        baseMap.set(key, entity);
+    }
+    const branchMap = new Map();
+    for (const entity of branchEntities) {
+        const key = entityKey(entity);
+        branchMap.set(key, entity);
+    }
+    // Classify entities
+    const added = [];
+    const removed = [];
+    const modified = [];
+    const unchanged = [];
+    // Added: in branch but not base
+    for (const [key, entity] of branchMap) {
+        if (!baseMap.has(key)) {
+            added.push({
+                id: entity.id,
+                name: entityName(entity),
+                sourceFile: entity._sourceFile || null,
+                layer: entityLayer(entity),
+            });
+        }
+    }
+    // Removed: in base but not branch
+    for (const [key, entity] of baseMap) {
+        if (!branchMap.has(key)) {
+            removed.push({
+                id: entity.id,
+                name: entityName(entity),
+                sourceFile: entity._sourceFile || null,
+                layer: entityLayer(entity),
+            });
+        }
+    }
+    // Modified / Unchanged: in both
+    for (const [key, branchEntity] of branchMap) {
+        const baseEntity = baseMap.get(key);
+        if (!baseEntity)
+            continue; // already in added
+        const changedFields = compareEntityFields(baseEntity, branchEntity);
+        if (changedFields.length > 0) {
+            modified.push({
+                id: branchEntity.id,
+                name: entityName(branchEntity),
+                sourceFile: branchEntity._sourceFile || null,
+                layer: entityLayer(branchEntity),
+                changedFields,
+            });
+        }
+        else if (args.include_unchanged) {
+            unchanged.push({
+                id: branchEntity.id,
+                name: entityName(branchEntity),
+                sourceFile: branchEntity._sourceFile || null,
+                layer: entityLayer(branchEntity),
+            });
+        }
+    }
+    // Count unique files touched
+    const touchedFiles = new Set();
+    for (const e of [...added, ...removed, ...modified]) {
+        if (e.sourceFile)
+            touchedFiles.add(e.sourceFile);
+    }
+    const totalChanges = added.length + removed.length + modified.length;
+    const result = {
+        base: {
+            project: baseManifest?.projectName || args.project || 'default',
+            commitSha: baseManifest?.commitSha || '',
+            entityCount: baseEntities.length,
+        },
+        branch: {
+            path: args.worktree_path,
+            commitSha: branchData.commitSha,
+            entityCount: branchData.entityCount,
+        },
+        summary: {
+            added: added.length,
+            removed: removed.length,
+            modified: modified.length,
+            unchanged: baseEntities.length - removed.length - modified.length,
+        },
+        added,
+        removed,
+        modified,
+        _summary: `Branch modifies ${totalChanges} entities (${added.length} added, ${removed.length} removed, ${modified.length} modified) across ${touchedFiles.size} files`,
+    };
+    if (args.include_unchanged) {
+        result.unchanged = unchanged;
+    }
+    return result;
+}
+// ─── Conflict Tier Classification ─────────────────────────────────
+const ZONE_1 = new Set(['edges', 'imports', 'ε']); // Header / Far from body
+const ZONE_2 = new Set(['struct', 'σ', 'constraints', 'κ', 'traits', 'τ', 'ownership', 'λ']); // Signature / Decorators (High collision risk)
+const ZONE_3 = new Set(['semantics', 'Σ', 'data', 'δ', 'runtime', 'ρ']); // Body / Implementation
+function getZones(dimensions) {
+    const zones = new Set();
+    for (const d of dimensions) {
+        const lower = d.toLowerCase();
+        if (ZONE_1.has(lower))
+            zones.add(1);
+        if (ZONE_2.has(lower))
+            zones.add(2);
+        if (ZONE_3.has(lower))
+            zones.add(3);
+    }
+    return zones;
+}
+function classifyConflictTier(taskA, taskB) {
+    // Check entity overlap
+    const sharedEntities = [];
+    for (const id of taskA.entityIds) {
+        if (taskB.entityIds.has(id)) {
+            sharedEntities.push(id);
+        }
+    }
+    if (sharedEntities.length > 0) {
+        // Both touch same entity. Check dimensions to see if we can downgrade from Tier 4 (Sequential) to Tier 3 (Parallelizable Orthogonal)
+        if (taskA.dimensions.size > 0 && taskB.dimensions.size > 0) {
+            const zonesA = getZones(taskA.dimensions);
+            const zonesB = getZones(taskB.dimensions);
+            let spatialCollision = false;
+            for (const z of zonesA) {
+                if (zonesB.has(z))
+                    spatialCollision = true;
+            }
+            if (!spatialCollision) {
+                return {
+                    tier: 3,
+                    reason: `${sharedEntities.length} shared entities, but orthogonal Spatial Zones (Tier 3) — safe to parallelize`,
+                    sharedFiles: [],
+                    sharedEntities,
+                };
+            }
+        }
+        return {
+            tier: 4,
+            reason: `${sharedEntities.length} shared entities in same/unknown Spatial Zone (Tier 4) — MUST sequence to prevent git conflict`,
+            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 (sharedFiles.length === 0) {
+        return {
+            tier: 1,
+            reason: 'No shared files — safe to parallelize',
+            sharedFiles: [],
+            sharedEntities: [],
+        };
+    }
+    return {
+        tier: 2,
+        reason: `${sharedFiles.length} shared files but different entities — git auto-merge handles it`,
+        sharedFiles,
+        sharedEntities: [],
+    };
+}
+// ─── Execution Plan Builder ───────────────────────────────────────
+/**
+ * Build execution plan from tier-4 conflict graph using connected components.
+ * Tasks with no tier-4 edges to each other run in parallel.
+ * Tasks in the same tier-4 component run sequentially.
+ */
+function buildExecutionPlan(taskIds, tier4Edges) {
+    // Build adjacency list for tier-4 conflicts
+    const adj = new Map();
+    for (const id of taskIds) {
+        adj.set(id, new Set());
+    }
+    for (const [a, b] of tier4Edges) {
+        adj.get(a)?.add(b);
+        adj.get(b)?.add(a);
+    }
+    // Find connected components via BFS
+    const visited = new Set();
+    const components = [];
+    for (const id of taskIds) {
+        if (visited.has(id))
+            continue;
+        const component = [];
+        const queue = [id];
+        visited.add(id);
+        while (queue.length > 0) {
+            const current = queue.shift();
+            component.push(current);
+            const neighbors = adj.get(current);
+            if (neighbors) {
+                for (const neighbor of neighbors) {
+                    if (!visited.has(neighbor)) {
+                        visited.add(neighbor);
+                        queue.push(neighbor);
+                    }
+                }
+            }
+        }
+        components.push(component);
+    }
+    // Build groups
+    const groups = components.map(component => {
+        if (component.length === 1) {
+            return { tasks: component, sequential: false };
+        }
+        return { tasks: component, sequential: true, order: component };
+    });
+    // Count parallelizable groups
+    const parallelGroups = groups.length;
+    const sequentialCount = groups.filter(g => g.sequential).length;
+    const parallelCount = groups.filter(g => !g.sequential).length;
+    let summaryParts = [`${taskIds.length} tasks`];
+    if (parallelCount > 0) {
+        summaryParts.push(`${parallelCount === taskIds.length ? 'all' : parallelCount} can run in parallel`);
+    }
+    if (sequentialCount > 0) {
+        const seqTasks = groups.filter(g => g.sequential).reduce((sum, g) => sum + g.tasks.length, 0);
+        summaryParts.push(`${seqTasks} must be sequenced (${sequentialCount} sequential group${sequentialCount > 1 ? 's' : ''})`);
+    }
+    return {
+        parallelGroups,
+        groups,
+        _summary: summaryParts.join(': '),
+    };
+}
+// ─── Tool: conflict_matrix ────────────────────────────────────────
+export function conflictMatrix(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const { tasks } = args;
+    if (!tasks || tasks.length < 2) {
+        return { error: 'At least 2 tasks are required to compute a conflict matrix.' };
+    }
+    const warnings = [];
+    // Resolve entity sets for each task
+    const resolvedTasks = [];
+    for (const task of tasks) {
+        const entityIds = new Set();
+        const files = new Set();
+        const entities = [];
+        const notFound = [];
+        const dimensions = new Set(task.dimensions || []);
+        for (const nameOrId of task.entity_ids) {
+            const entity = loader.getEntityById(nameOrId, args.project)
+                || loader.getEntityByName(nameOrId, args.project);
+            if (entity) {
+                entityIds.add(entity.id);
+                entities.push(entity);
+                if (entity._sourceFile)
+                    files.add(entity._sourceFile);
+            }
+            else {
+                notFound.push(nameOrId);
+            }
+        }
+        if (notFound.length > 0) {
+            warnings.push(`Task "${task.id}": entities not found: ${notFound.join(', ')}`);
+        }
+        // Expand blast radius if requested
+        if (task.expand_blast_radius && entityIds.size > 0) {
+            const g = getGraph(args.project);
+            const blastResult = computeBlastRadius(g, entityIds);
+            for (const affectedId of blastResult.affected) {
+                if (!entityIds.has(affectedId)) {
+                    entityIds.add(affectedId);
+                    const affectedEntity = g.entityById.get(affectedId);
+                    if (affectedEntity) {
+                        entities.push(affectedEntity);
+                        if (affectedEntity._sourceFile)
+                            files.add(affectedEntity._sourceFile);
+                    }
+                }
+            }
+        }
+        resolvedTasks.push({ id: task.id, entityIds, files, entities, dimensions });
+    }
+    // Pairwise comparison
+    const matrix = [];
+    const tier4Edges = [];
+    for (let i = 0; i < resolvedTasks.length; i++) {
+        for (let j = i + 1; j < resolvedTasks.length; j++) {
+            const taskA = resolvedTasks[i];
+            const taskB = resolvedTasks[j];
+            const result = classifyConflictTier(taskA, taskB);
+            const entry = {
+                taskA: taskA.id,
+                taskB: taskB.id,
+                tier: result.tier,
+                reason: result.reason,
+            };
+            if (result.sharedFiles.length > 0)
+                entry.sharedFiles = result.sharedFiles;
+            if (result.sharedEntities.length > 0)
+                entry.sharedEntities = result.sharedEntities;
+            matrix.push(entry);
+            if (result.tier === 4) {
+                tier4Edges.push([taskA.id, taskB.id]);
+            }
+        }
+    }
+    // Build execution plan
+    const taskIds = resolvedTasks.map(t => t.id);
+    const executionPlan = buildExecutionPlan(taskIds, tier4Edges);
+    const result = {
+        taskCount: tasks.length,
+        matrix,
+        executionPlan,
+    };
+    if (warnings.length > 0) {
+        result.warnings = warnings;
+    }
+    return result;
+}

package/dist/tools/functors.d.ts

@@ -66,3 +66,35 @@ export declare function reportActualBurn(args: {
     project?: string;
     notes?: string;
 }): Promise<unknown>;
+export declare function find_runtime_violations(args?: {
+    project?: string;
+}): unknown;
+export declare function find_ownership_violations(args?: {
+    project?: string;
+}): unknown;
+export declare function query_traits(args: {
+    trait: string;
+    project?: string;
+}): unknown;
+export declare function simulate_mutation(args: {
+    entity_id: string;
+    mutation: {
+        dimension: 'constraints' | 'traits';
+        change: {
+            add?: string[];
+            remove?: string[];
+        };
+    };
+    project?: string;
+}): unknown;
+export declare function query_data_targets(args: {
+    target_name: string;
+    project?: string;
+}): unknown;
+export declare function find_exposure_leaks(args?: {
+    project?: string;
+}): unknown;
+export declare function find_semantic_clones(args?: {
+    project?: string;
+    min_complexity?: number;
+}): unknown;

package/dist/tools/functors.js

@@ -6,7 +6,7 @@
  * coupling metrics, auth coverage, etc.) from the entity data.
  */
 import { computeBlastRadius } from '../graph.js';
-import { getLoader, getGraph, validateProject, entityLayer, entitySummary, } from './index.js';
+import { getLoader, getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
 import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, listPredictions, } from '../supabase.js';
 // ─── Layer ordering for violation detection ──────────────────────
 const LAYER_ORDER = {
@@ -866,3 +866,347 @@ export async function reportActualBurn(args) {
         _summary: `Prediction ${updated.id.slice(0, 8)}… closed. Predicted ${updated.predicted_total} tokens, actual ${updated.actual_total_tokens} tokens. Drift: ${updated.drift_ratio != null ? `${(updated.drift_ratio * 100).toFixed(1)}%` : 'N/A'}.`,
     };
 }
+// ─── Tool: find_runtime_violations (ρ Dimension) ─────────────────
+export function find_runtime_violations(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args?.project);
+    const violations = [];
+    for (const [callerId, calleeIds] of g.callees) {
+        const callerEntity = g.entityById.get(callerId);
+        if (!callerEntity)
+            continue;
+        const callerFramework = callerEntity.runtime?.framework || 'agnostic';
+        for (const calleeId of calleeIds) {
+            const calleeEntity = g.entityById.get(calleeId);
+            if (!calleeEntity)
+                continue;
+            const calleeFramework = calleeEntity.runtime?.framework;
+            // If caller is framework-agnostic but calls framework-specific code (e.g., pure logic calling React)
+            if (callerFramework === 'agnostic' && calleeFramework && calleeFramework !== 'agnostic') {
+                violations.push({
+                    caller: { ...entitySummary(callerEntity), framework: callerFramework },
+                    callee: { ...entitySummary(calleeEntity), framework: calleeFramework },
+                    issue: `Framework leak: Agnostic caller depends on ${calleeFramework}-specific callee`,
+                });
+            }
+            // If mixing frameworks directly (e.g., Vue calling React)
+            if (callerFramework !== 'agnostic' && calleeFramework && calleeFramework !== 'agnostic' && callerFramework !== calleeFramework) {
+                violations.push({
+                    caller: { ...entitySummary(callerEntity), framework: callerFramework },
+                    callee: { ...entitySummary(calleeEntity), framework: calleeFramework },
+                    issue: `Cross-framework boundary: ${callerFramework} calling ${calleeFramework}`,
+                });
+            }
+        }
+    }
+    return {
+        totalViolations: violations.length,
+        _summary: `Found ${violations.length} runtime/framework boundary violations (ρ dimension)`,
+        violations: violations.slice(0, 100),
+    };
+}
+// ─── Tool: find_ownership_violations (λ Dimension) ───────────────
+export function find_ownership_violations(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args?.project);
+    const violations = [];
+    for (const e of entities) {
+        if (!e.ownership || Object.keys(e.ownership).length === 0)
+            continue;
+        // We look for 'unsafe', 'escapes', 'mutates_borrowed', or complex lifetime constraints
+        const own = e.ownership;
+        if (own.unsafe) {
+            violations.push({
+                entity: entitySummary(e),
+                ownership_details: own,
+                issue: 'Unsafe memory access or pointer manipulation flagged',
+            });
+        }
+        else if (own.escapes) {
+            violations.push({
+                entity: entitySummary(e),
+                ownership_details: own,
+                issue: 'Value potentially escapes its lifetime boundary',
+            });
+        }
+        else if (own.mutates_borrowed) {
+            violations.push({
+                entity: entitySummary(e),
+                ownership_details: own,
+                issue: 'Attempts to mutate an immutably borrowed reference',
+            });
+        }
+    }
+    return {
+        totalViolations: violations.length,
+        _summary: `Found ${violations.length} entities with strict/violating ownership constraints (λ dimension)`,
+        violations: violations.slice(0, 100),
+    };
+}
+// ─── Tool: query_traits (τ Dimension) ────────────────────────────
+export function query_traits(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const target = args.trait.toLowerCase();
+    const loader = getLoader();
+    const entities = loader.getEntities(args.project);
+    const results = entities.filter(e => {
+        if (!e.traits)
+            return false;
+        // Handle array of strings [ 'asyncContext', 'generator' ]
+        if (Array.isArray(e.traits)) {
+            return e.traits.some(t => t.toLowerCase().includes(target));
+        }
+        // Handle structured traits { self: { fallible: true } }
+        if (typeof e.traits === 'object') {
+            const tr = e.traits;
+            if (tr.self && typeof tr.self === 'object') {
+                const selfTraits = tr.self;
+                for (const [key, val] of Object.entries(selfTraits)) {
+                    if (key.toLowerCase().includes(target) && val === true)
+                        return true;
+                }
+            }
+            if (tr.params && typeof tr.params === 'object') {
+                const paramTraits = tr.params;
+                for (const p of Object.values(paramTraits)) {
+                    if (p.bounds && Array.isArray(p.bounds) && p.bounds.some((b) => b.toLowerCase().includes(target)))
+                        return true;
+                    if (p.markers && Array.isArray(p.markers) && p.markers.some((m) => m.toLowerCase().includes(target)))
+                        return true;
+                }
+            }
+        }
+        return false;
+    });
+    return {
+        trait: args.trait,
+        total: results.length,
+        _summary: `Found ${results.length} entities implementing the '${args.trait}' trait (τ dimension)`,
+        entities: results.slice(0, 100).map(entitySummary),
+    };
+}
+// ─── Tool: simulate_mutation (The Physics Engine) ────────────────
+export function simulate_mutation(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const g = getGraph(args.project);
+    const targetEntity = loader.getEntityById(args.entity_id, args.project)
+        || loader.getEntityByName(args.entity_id, args.project);
+    if (!targetEntity) {
+        return { error: `Entity not found: ${args.entity_id}` };
+    }
+    const targetId = targetEntity.id;
+    const { dimension, change } = 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?
+    const fallout = [];
+    // Simulate Fallout: Traversal Upstream (Callers)
+    const upQueue = [[targetId, 0]];
+    const upVisited = new Set([targetId]);
+    while (upQueue.length > 0) {
+        const [currentId, depth] = upQueue.shift();
+        if (depth > 5)
+            continue; // bound simulation depth
+        const callerSet = g.callers.get(currentId);
+        if (!callerSet)
+            continue;
+        for (const callerId of callerSet) {
+            if (upVisited.has(callerId))
+                continue;
+            upVisited.add(callerId);
+            const callerEntity = g.entityById.get(callerId);
+            if (!callerEntity)
+                continue;
+            const callerConstraints = callerEntity.constraints;
+            const callerTraits = callerEntity.traits;
+            // Rule 1: Fallible Simulation
+            if (addedTags.includes('fallible') || addedTags.includes('throws')) {
+                const hasErrorHandling = callerConstraints?.errorHandling &&
+                    (callerConstraints.errorHandling.tryCatch || callerConstraints.errorHandling.catchClause);
+                if (!hasErrorHandling) {
+                    fallout.push({
+                        entity: entitySummary(callerEntity),
+                        distance: depth + 1,
+                        reason: `Calls a newly fallible pipeline but lacks error handling.`,
+                        requiredFix: `Wrap call to ${currentId} in try/catch or propagate error.`,
+                    });
+                    // Error propagates up if not caught, so we continue queueing
+                    upQueue.push([callerId, depth + 1]);
+                }
+            }
+            // Rule 2: Auth / Security Simulation
+            else if (addedTags.includes('auth') || addedTags.includes('secure')) {
+                // Does the caller provide Auth? Check constraints.auth or if they are a known auth middleware
+                const hasAuth = callerConstraints?.auth || callerTraits?.self?.authContext;
+                const isMiddleware = entityLayer(callerEntity) === 'middleware';
+                if (!hasAuth && !isMiddleware) {
+                    fallout.push({
+                        entity: entitySummary(callerEntity),
+                        distance: depth + 1,
+                        reason: `Upstream path is unauthenticated but downstream requires auth.`,
+                        requiredFix: `Add authentication context to ${entityName(callerEntity)} or its router.`,
+                    });
+                    upQueue.push([callerId, depth + 1]);
+                }
+            }
+            // Generic unhandled propagation
+            else {
+                upQueue.push([callerId, depth + 1]);
+            }
+        }
+    }
+    return {
+        target: entitySummary(targetEntity),
+        mutation: args.mutation,
+        affectedEntitiesCount: fallout.length,
+        _summary: `Simulating adding [${addedTags.join(', ')}] to ${entityName(targetEntity)}. This structurally breaks ${fallout.length} upstream entities.`,
+        fallout,
+    };
+}
+// ─── Tool: query_data_targets (δ Dimension Reverse-Index) ────────
+export function query_data_targets(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args.project);
+    const target = args.target_name.toLowerCase();
+    const readers = [];
+    const writers = [];
+    for (const e of entities) {
+        if (!e.data)
+            continue;
+        let isReader = false;
+        let isWriter = false;
+        // Check tables
+        if (Array.isArray(e.data.tables) && e.data.tables.some(t => String(t).toLowerCase() === target)) {
+            // By default, if they touch a table but don't specify mutation, we assume read
+            isReader = true;
+        }
+        // Check inputs (sources)
+        if (Array.isArray(e.data.inputs)) {
+            if (e.data.inputs.some(i => i && typeof i === 'object' && String(i.name || i.source).toLowerCase() === target)) {
+                isReader = true;
+            }
+        }
+        else if (Array.isArray(e.data.sources)) {
+            if (e.data.sources.some(s => String(s).toLowerCase() === target)) {
+                isReader = true;
+            }
+        }
+        // Check mutations
+        if (Array.isArray(e.data.mutations)) {
+            if (e.data.mutations.some(m => m && typeof m === 'object' && String(m.target).toLowerCase() === target)) {
+                isWriter = true;
+            }
+        }
+        if (isWriter) {
+            writers.push(entitySummary(e));
+        }
+        else if (isReader) {
+            readers.push(entitySummary(e));
+        }
+    }
+    return {
+        target: args.target_name,
+        totalInteractions: readers.length + writers.length,
+        writersCount: writers.length,
+        readersCount: readers.length,
+        _summary: `Found ${writers.length} entities mutating and ${readers.length} entities reading data target '${args.target_name}' (δ dimension reverse-index)`,
+        writers: writers.slice(0, 50),
+        readers: readers.slice(0, 50),
+    };
+}
+// ─── Tool: find_exposure_leaks (χ Context Dimension) ─────────────
+export function find_exposure_leaks(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const g = getGraph(args?.project);
+    const leaks = [];
+    for (const [callerId, calleeIds] of g.callees) {
+        const callerEntity = g.entityById.get(callerId);
+        if (!callerEntity)
+            continue;
+        const callerVisibility = callerEntity.context?.visibility || callerEntity.context?.exposure;
+        if (callerVisibility !== 'public' && callerVisibility !== 'api')
+            continue;
+        for (const calleeId of calleeIds) {
+            const calleeEntity = g.entityById.get(calleeId);
+            if (!calleeEntity)
+                continue;
+            const calleeVisibility = calleeEntity.context?.visibility;
+            if (calleeVisibility === 'private') {
+                leaks.push({
+                    publicCaller: entitySummary(callerEntity),
+                    privateCallee: entitySummary(calleeEntity),
+                    issue: `Exposure Leak: Public/API entity directly calls deeply private entity.`,
+                });
+            }
+        }
+    }
+    return {
+        totalLeaks: leaks.length,
+        _summary: `Found ${leaks.length} architectural visibility leaks where public edges bypass internal boundaries to reach private entities (χ dimension)`,
+        leaks: leaks.slice(0, 100),
+    };
+}
+// ─── Tool: find_semantic_clones (Σ Logic Dimension) ──────────────
+import { createHash } from 'crypto';
+export function find_semantic_clones(args) {
+    const projErr = validateProject(args?.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    const entities = loader.getEntities(args?.project);
+    const { min_complexity = 5 } = args || {};
+    const logicHashes = new Map();
+    for (const e of entities) {
+        if (!e.semantics || !Array.isArray(e.semantics) || e.semantics.length < min_complexity) {
+            continue;
+        }
+        // A highly simplified logic stringification that ignores specific variable names
+        // but captures the structural AST shape. 
+        // In a production scenario, you would normalize variable identifiers ($1, $2) here.
+        const shapeString = JSON.stringify(e.semantics, (key, value) => {
+            // Omit line numbers and exact variable names to find structural clones
+            if (key === 'loc' || key === 'name' || key === 'value' || key === 'id')
+                return undefined;
+            return value;
+        });
+        const hash = createHash('sha256').update(shapeString).digest('hex');
+        if (!logicHashes.has(hash))
+            logicHashes.set(hash, []);
+        logicHashes.get(hash).push(e);
+    }
+    const clones = [];
+    for (const [hash, group] of logicHashes.entries()) {
+        if (group.length > 1) {
+            clones.push({
+                count: group.length,
+                entities: group.map(e => entitySummary(e)),
+            });
+        }
+    }
+    // Sort by highest duplication count
+    clones.sort((a, b) => b.count - a.count);
+    let totalDuplicatedEntities = 0;
+    for (const c of clones)
+        totalDuplicatedEntities += c.count;
+    return {
+        cloneGroupsFound: clones.length,
+        totalDuplicatedEntities,
+        _summary: `Found ${clones.length} semantic clone groups involving ${totalDuplicatedEntities} total entities (Σ dimension analysis)`,
+        cloneGroups: clones.slice(0, 50),
+    };
+}

package/dist/types.d.ts

@@ -11,6 +11,10 @@ export interface JstfEntity {
     _sourceFile?: string | null;
     _sourceLanguage?: string;
     _project?: string;
+    _sourceLocation?: {
+        startLine: number;
+        endLine: number;
+    };
     /** Structure: function shape, signature, modifiers */
     struct?: {
         name?: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@papyruslabsai/seshat-mcp",
-  "version": "0.4.2",
+  "version": "0.7.0",
   "description": "Semantic MCP server — exposes a codebase's structure, dependencies, and constraints as queryable tools",
   "type": "module",
   "bin": {
@@ -30,6 +30,12 @@
     "url": "https://github.com/papyruslabs-ai/seshat.git",
     "directory": "packages/seshat-mcp"
   },
-  "keywords": ["mcp", "semantic", "code-analysis", "seshat", "static-analysis"],
+  "keywords": [
+    "mcp",
+    "semantic",
+    "code-analysis",
+    "seshat",
+    "static-analysis"
+  ],
   "license": "MIT"
 }