@papyruslabsai/seshat-mcp 0.4.2 → 0.6.0

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, } from './tools/functors.js';
+import { diffBundle, conflictMatrix, } from './tools/diff.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
  * Discover project directories from SESHAT_PROJECTS env var.
@@ -386,6 +388,101 @@ 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'],
+        },
+    },
+    // ─── 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 +538,7 @@ async function main() {
     }
     const server = new Server({
         name: serverLabel,
-        version: '0.4.2',
+        version: '0.5.0',
     }, {
         capabilities: {
             tools: {},
@@ -531,6 +628,23 @@ 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;
+                // 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,13 @@ 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;

package/dist/tools/functors.js

@@ -866,3 +866,129 @@ 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),
+    };
+}

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.6.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"
 }