@papyruslabsai/seshat-mcp 0.8.0 → 0.9.0

package/dist/index.js

@@ -34,7 +34,7 @@ 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, find_runtime_violations, find_ownership_violations, query_traits, simulate_mutation, query_data_targets, find_exposure_leaks, find_semantic_clones, } 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, create_symbol, } from './tools/functors.js';
 import { diffBundle, conflictMatrix, } from './tools/diff.js';
 // ─── Project Discovery ───────────────────────────────────────────
 /**
@@ -388,10 +388,10 @@ const TOOLS = [
             },
         },
     },
-    // ─── Semantic (9D) JSTF-T Tools ─────────────────────────────────
+    // ─── Analysis & Impact 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.',
+        description: 'Analyze the call graph for runtime environment leaks. Finds architectural boundary issues 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: {
@@ -401,7 +401,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'Analyze the codebase for memory and lifecycle constraints. Flags entities with complex ownership rules, unsafe blocks, escaping boundaries, or illegal mutability patterns on borrowed references.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -411,7 +411,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'Search the codebase for specific functional capabilities. Allows you to find entities by their abstract traits (e.g., "fallible", "asyncContext", "generator") regardless of their structural syntax.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -426,20 +426,20 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'The Impact Simulator. Proposes a hypothetical change to an entity (like adding a "fallible" or "auth" requirement) and simulates the architectural 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.',
+                    description: 'The target entity to analyze.',
                 },
                 mutation: {
                     type: 'object',
                     description: 'The hypothetical change to apply.',
                     properties: {
-                        dimension: { type: 'string', enum: ['constraints', 'traits'] },
+                        dimension: { type: 'string', enum: ['constraints', 'traits'], description: 'The attribute scope to mutate.' },
                         change: {
                             type: 'object',
                             properties: {
@@ -456,7 +456,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'Search the codebase for data interactions 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: {
@@ -471,7 +471,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'Analyze the call graph for architectural visibility leaks. Flags paths where a "public" or "api" entity directly accesses a "private" internal entity, potentially leaking sensitive data or bypassing internal service boundaries.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -481,7 +481,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'Analyze the codebase for duplicated logic blocks. Normalizes variables and compares code structure to identify identical algorithms written across different files or even different languages.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -493,10 +493,37 @@ const TOOLS = [
             },
         },
     },
-    // ─── Diff Tools ─────────────────────────────────────────────────
+    {
+        name: 'create_symbol',
+        description: 'Register a new code symbol in the architectural graph. This does not write to disk, but allows the Impact Simulator and Conflict Matrix to reason about a symbol that is pending creation. Essential for planning new features that introduce new files or modules.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project: projectParam,
+                id: {
+                    type: 'string',
+                    description: 'The unique ID or name for the new symbol.',
+                },
+                source_file: {
+                    type: 'string',
+                    description: 'The relative path to the file where this symbol will be created.',
+                },
+                layer: {
+                    type: 'string',
+                    description: 'The architectural layer (e.g., "service", "route", "component").',
+                },
+                description: {
+                    type: 'string',
+                    description: 'Brief description of the symbol\'s purpose.',
+                },
+            },
+            required: ['id', 'source_file'],
+        },
+    },
+    // ─── 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.',
+        description: 'Compare code structure between a worktree and the loaded project. Shows which symbols were added, removed, or modified — not a line diff, but a structural diff showing changed signatures, dependencies, and implementation logic.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -515,7 +542,7 @@ const TOOLS = [
     },
     {
         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.',
+        description: 'Given multiple tasks, classify every task pair into conflict tiers to determine parallelization safety. Tier 1 (different files, safe), Tier 2 (same file, different symbols, safe), Tier 3 (same symbol, orthogonal changes like imports vs logic, risky but parallelizable), Tier 4 (same symbol, overlapping changes, MUST sequence). Passing "scopes" per task enables Tier 3 downgrades.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -532,16 +559,16 @@ const TOOLS = [
                             entity_ids: {
                                 type: 'array',
                                 items: { type: 'string' },
-                                description: 'Entity IDs or names that this task will modify',
+                                description: 'Symbol names or IDs 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.',
+                                description: 'Optional: Code scopes this task will modify (e.g., "edges", "struct", "semantics", "constraints"). Used to downgrade conflicts via spatial separation.',
                             },
                             expand_blast_radius: {
                                 type: 'boolean',
-                                description: 'Include transitively affected entities in the conflict check (default: false)',
+                                description: 'Include transitively affected symbols in the conflict check (default: false)',
                             },
                         },
                         required: ['id', 'entity_ids'],
@@ -697,7 +724,7 @@ async function main() {
                 case 'report_actual_burn':
                     result = await reportActualBurn(args);
                     break;
-                // Semantic (9D) JSTF-T Tools
+                // Analysis & Impact Tools
                 case 'find_runtime_violations':
                     result = find_runtime_violations(args);
                     break;
@@ -719,6 +746,9 @@ async function main() {
                 case 'find_semantic_clones':
                     result = find_semantic_clones(args);
                     break;
+                case 'create_symbol':
+                    result = create_symbol(args);
+                    break;
                 // Diff Tools
                 case 'diff_bundle':
                     result = await diffBundle(args);

package/dist/loader.d.ts

@@ -46,5 +46,10 @@ export declare class MultiLoader {
     isMultiProject(): boolean;
     isLoaded(): boolean;
     hasProject(name: string): boolean;
+    /**
+     * Register a virtual entity in memory.
+     * Used for Phase 1/2 of the Harness to reason about entities that haven't been written to disk yet.
+     */
+    registerVirtualEntity(entity: JstfEntity, project?: string): void;
     totalEntities(): number;
 }

package/dist/loader.js

@@ -190,6 +190,28 @@ export class MultiLoader {
     hasProject(name) {
         return this.projects.has(name);
     }
+    /**
+     * Register a virtual entity in memory.
+     * Used for Phase 1/2 of the Harness to reason about entities that haven't been written to disk yet.
+     */
+    registerVirtualEntity(entity, project) {
+        if (!this.loaded)
+            this.load();
+        const p = this.resolveProject(project);
+        if (!p)
+            return;
+        const entities = this.projectEntities.get(p) || [];
+        entity._project = p;
+        // If entity already exists, update it, otherwise append
+        const existingIdx = entities.findIndex(e => e.id === entity.id);
+        if (existingIdx !== -1) {
+            entities[existingIdx] = { ...entities[existingIdx], ...entity };
+        }
+        else {
+            entities.push(entity);
+        }
+        this.projectEntities.set(p, entities);
+    }
     totalEntities() {
         let total = 0;
         for (const entities of this.projectEntities.values()) {

package/dist/tools/diff.js

@@ -262,13 +262,13 @@ export async function diffBundle(args) {
     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 ZONE_1 = new Set(['edges', 'imports']); // Header / Dependencies
+const ZONE_2 = new Set(['struct', 'constraints', 'traits', 'ownership']); // Signature / Modifiers
+const ZONE_3 = new Set(['semantics', 'data', 'runtime']); // Logic / Implementation        
+function getZones(scopes) {
     const zones = new Set();
-    for (const d of dimensions) {
-        const lower = d.toLowerCase();
+    for (const s of scopes) {
+        const lower = s.toLowerCase();
         if (ZONE_1.has(lower))
             zones.add(1);
         if (ZONE_2.has(lower))
@@ -279,7 +279,7 @@ function getZones(dimensions) {
     return zones;
 }
 function classifyConflictTier(taskA, taskB) {
-    // Check entity overlap
+    // Check symbol overlap
     const sharedEntities = [];
     for (const id of taskA.entityIds) {
         if (taskB.entityIds.has(id)) {
@@ -287,7 +287,7 @@ function classifyConflictTier(taskA, taskB) {
         }
     }
     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)
+        // Both touch same symbol. Check scopes 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);
@@ -299,7 +299,7 @@ function classifyConflictTier(taskA, taskB) {
             if (!spatialCollision) {
                 return {
                     tier: 3,
-                    reason: `${sharedEntities.length} shared entities, but orthogonal Spatial Zones (Tier 3) — safe to parallelize`,
+                    reason: `${sharedEntities.length} shared symbols, but orthogonal change scopes (Tier 3) — safe to parallelize`,
                     sharedFiles: [],
                     sharedEntities,
                 };
@@ -307,7 +307,7 @@ function classifyConflictTier(taskA, taskB) {
         }
         return {
             tier: 4,
-            reason: `${sharedEntities.length} shared entities in same/unknown Spatial Zone (Tier 4) — MUST sequence to prevent git conflict`,
+            reason: `${sharedEntities.length} shared symbols in same/unknown change scope (Tier 4) — MUST sequence to prevent merge conflict`,
             sharedFiles: [],
             sharedEntities,
         };
@@ -329,7 +329,7 @@ function classifyConflictTier(taskA, taskB) {
     }
     return {
         tier: 2,
-        reason: `${sharedFiles.length} shared files but different entities — git auto-merge handles it`,
+        reason: `${sharedFiles.length} shared files but different symbols — safe to parallelize`,
         sharedFiles,
         sharedEntities: [],
     };

package/dist/tools/functors.d.ts

@@ -98,3 +98,10 @@ export declare function find_semantic_clones(args?: {
     project?: string;
     min_complexity?: number;
 }): unknown;
+export declare function create_symbol(args: {
+    id: string;
+    source_file: string;
+    layer?: string;
+    project?: string;
+    description?: string;
+}): unknown;

package/dist/tools/functors.js

@@ -5,6 +5,7 @@
  * Each tool computes derived insights (dead code, layer violations,
  * coupling metrics, auth coverage, etc.) from the entity data.
  */
+import path from 'path';
 import { computeBlastRadius } from '../graph.js';
 import { getLoader, getGraph, validateProject, entityName, entityLayer, entitySummary, } from './index.js';
 import { isSupabaseConfigured, insertPrediction, updateActualBurn, abandonPrediction, listPredictions, } from '../supabase.js';
@@ -866,7 +867,7 @@ 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) ─────────────────
+// ─── Tool: find_runtime_violations (Runtime Context) ────────────
 export function find_runtime_violations(args) {
     const projErr = validateProject(args?.project);
     if (projErr)
@@ -903,11 +904,11 @@ export function find_runtime_violations(args) {
     }
     return {
         totalViolations: violations.length,
-        _summary: `Found ${violations.length} runtime/framework boundary violations (ρ dimension)`,
+        _summary: `Found ${violations.length} runtime/framework boundary violations`,
         violations: violations.slice(0, 100),
     };
 }
-// ─── Tool: find_ownership_violations (λ Dimension) ───────────────
+// ─── Tool: find_ownership_violations (Ownership & Lifetimes) ─────
 export function find_ownership_violations(args) {
     const projErr = validateProject(args?.project);
     if (projErr)
@@ -944,11 +945,11 @@ export function find_ownership_violations(args) {
     }
     return {
         totalViolations: violations.length,
-        _summary: `Found ${violations.length} entities with strict/violating ownership constraints (λ dimension)`,
+        _summary: `Found ${violations.length} symbols with strict/violating ownership constraints`,
         violations: violations.slice(0, 100),
     };
 }
-// ─── Tool: query_traits (τ Dimension) ────────────────────────────
+// ─── Tool: query_traits (Trait Search) ───────────────────────────
 export function query_traits(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -988,11 +989,11 @@ export function query_traits(args) {
     return {
         trait: args.trait,
         total: results.length,
-        _summary: `Found ${results.length} entities implementing the '${args.trait}' trait (τ dimension)`,
+        _summary: `Found ${results.length} symbols implementing the '${args.trait}' trait`,
         entities: results.slice(0, 100).map(entitySummary),
     };
 }
-// ─── Tool: simulate_mutation (The Physics Engine) ────────────────
+// ─── Tool: simulate_mutation (Impact Simulator) ──────────────────
 export function simulate_mutation(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -1002,7 +1003,7 @@ export function simulate_mutation(args) {
     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}` };
+        return { error: `Symbol not found: ${args.entity_id}` };
     }
     const targetId = targetEntity.id;
     const { dimension, change } = args.mutation;
@@ -1037,7 +1038,7 @@ export function simulate_mutation(args) {
                     fallout.push({
                         entity: entitySummary(callerEntity),
                         distance: depth + 1,
-                        reason: `Calls a newly fallible pipeline but lacks error handling.`,
+                        reason: `Calls a newly fallible path 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
@@ -1068,12 +1069,12 @@ export function simulate_mutation(args) {
     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.`,
+        affectedSymbolsCount: fallout.length,
+        _summary: `Simulating adding [${addedTags.join(', ')}] to ${entityName(targetEntity)}. This structurally impacts ${fallout.length} upstream symbols.`,
         fallout,
     };
 }
-// ─── Tool: query_data_targets (δ Dimension Reverse-Index) ────────
+// ─── Tool: query_data_targets (Data Flow Analysis) ──────────────
 export function query_data_targets(args) {
     const projErr = validateProject(args.project);
     if (projErr)
@@ -1122,12 +1123,12 @@ export function query_data_targets(args) {
         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)`,
+        _summary: `Found ${writers.length} symbols mutating and ${readers.length} symbols reading data target '${args.target_name}'`,
         writers: writers.slice(0, 50),
         readers: readers.slice(0, 50),
     };
 }
-// ─── Tool: find_exposure_leaks (χ Context Dimension) ─────────────
+// ─── Tool: find_exposure_leaks (Architectural Visibility) ───────
 export function find_exposure_leaks(args) {
     const projErr = validateProject(args?.project);
     if (projErr)
@@ -1150,18 +1151,18 @@ export function find_exposure_leaks(args) {
                 leaks.push({
                     publicCaller: entitySummary(callerEntity),
                     privateCallee: entitySummary(calleeEntity),
-                    issue: `Exposure Leak: Public/API entity directly calls deeply private entity.`,
+                    issue: `Exposure Leak: Public/API symbol directly calls deeply private internal implementation.`,
                 });
             }
         }
     }
     return {
         totalLeaks: leaks.length,
-        _summary: `Found ${leaks.length} architectural visibility leaks where public edges bypass internal boundaries to reach private entities (χ dimension)`,
+        _summary: `Found ${leaks.length} architectural visibility leaks where public paths bypass internal boundaries`,
         leaks: leaks.slice(0, 100),
     };
 }
-// ─── Tool: find_semantic_clones (Σ Logic Dimension) ──────────────
+// ─── Tool: find_semantic_clones (Logic Analysis) ────────────────
 import { createHash } from 'crypto';
 export function find_semantic_clones(args) {
     const projErr = validateProject(args?.project);
@@ -1205,8 +1206,44 @@ export function find_semantic_clones(args) {
         totalDuplicatedEntities += c.count;
     return {
         cloneGroupsFound: clones.length,
-        totalDuplicatedEntities,
-        _summary: `Found ${clones.length} semantic clone groups involving ${totalDuplicatedEntities} total entities (Σ dimension analysis)`,
+        totalDuplicatedSymbols: totalDuplicatedEntities,
+        _summary: `Found ${clones.length} logic clone groups involving ${totalDuplicatedEntities} symbols`,
         cloneGroups: clones.slice(0, 50),
     };
 }
+// ─── Tool: create_symbol (Virtual Entry) ─────────────────────────
+export function create_symbol(args) {
+    const projErr = validateProject(args.project);
+    if (projErr)
+        return { error: projErr };
+    const loader = getLoader();
+    // Create a skeleton JSTF-T entity
+    const virtualEntity = {
+        id: args.id,
+        _sourceFile: args.source_file,
+        sourceFile: args.source_file,
+        context: {
+            layer: args.layer || 'other',
+            visibility: 'public',
+            module: path.basename(args.source_file, path.extname(args.source_file)),
+        },
+        struct: {
+            name: args.id,
+            type: 'pending_creation'
+        },
+        constraints: {},
+        traits: { self: {} },
+        runtime: { framework: 'agnostic' },
+        edges: { calls: [], imports: [] },
+        semantics: [],
+        _virtual: true,
+        _description: args.description
+    };
+    loader.registerVirtualEntity(virtualEntity, args.project);
+    return {
+        success: true,
+        id: args.id,
+        sourceFile: args.source_file,
+        _summary: `Registered virtual symbol '${args.id}' in ${args.source_file}. Other tools can now reason about this symbol prior to its physical creation.`,
+    };
+}

package/package.json

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