Grafo de código

Cuatro consultas sobre el índice propio del taller: preciso en Go, heurístico en el resto, con una confianza por arista.

Qué es#

Cuatro preguntas que el índice sabe responder, cada una con su herramienta de agente y su comando humano.

Pregunta	Herramienta MCP	Comando humano	Responde con
Muéstrame el cuerpo de esta función	`code_snippet`	`orch symbols snippet <name>`	`{symbol, start_line, end_line, body, file_bytes}`
¿Quién la llama y a quién llama?	`trace_path`	`orch symbols trace <name>`	`{root, nodes, edges}`, una confianza por arista
¿Qué rompe este cambio?	`impact`	`orch symbols impact [path...]`	`{paths, touched, callers, edges}`
¿Cómo se ve este repositorio?	`architecture`	`orch symbols arch`	`{dirs, edges}` por directorio

trace_path acepta un direction opcional (callers, callees o both) y una depth de 1 a 5, con 2 por defecto. impact sin argumentos lee los cambios de tu propio checkout; dale paths[], un symbol o un git_range para preguntar por otra cosa. code_snippet devuelve a lo sumo max_lines líneas, 120 por defecto.

Tu propio código siempre se puede leer#

El proyecto de quien llama sale de su sesión —el asiento de un worker despachado nombra tanto su proyecto como su worktree— o, si es un Chair, del argumento project o del cwd. El índice guarda la ruta relativa a la raíz que la indexó más el proyecto al que pertenece, nunca una ruta absoluta, así que un mismo índice le responde al Chair desde el checkout del proyecto y al worker desde su worktree. Las cuatro herramientas devuelven ahí símbolos locales (sin etiqueta).

"Solo símbolos compartidos" es una regla sobre cruzar un límite, no sobre leer tu propio checkout: únicamente project: nombrando otro proyecto queda restringido a símbolos orch:export, y uno sin publicar se rechaza con todas las letras.

Cada respuesta tiene techo#

Una respuesta son tokens que se pagan en el turno en que llega y en cada turno que sigue en contexto, así que cada herramienta tiene un presupuesto duro de bytes y degrada para entrar en él en vez de desbordarlo:

Herramienta	Techo	Qué suelta, en orden
`trace_path`	2.000 B	aristas, luego todo salvo los cinco nodos mejor rankeados, luego un `hint`
`impact`	3.000 B	aristas, luego los llamadores de segundo salto, luego un `hint`
`architecture`	4.000 B	aristas, luego la lista de símbolos top, luego un `hint`
`code_snippet`	cuerpo + 200 B	el cuerpo mismo se topa en 6 KB por encima de `max_lines`

Las filas se ordenan por cuántas referencias apuntan a ellas y se cortan en limit (20 por defecto); una lista cortada trae has_more: true y un cursor para seguir. verbose: true devuelve la forma completa sin topes. Un nombre que no está responde {found: false, hint, did_you_mean} — nunca un error crudo, porque un error crudo es lo que manda al agente de vuelta al grep.

Por qué existe#

Leer un archivo entero para encontrar una función es el hábito más caro que tiene un agente. Un snippet por rango de líneas cuesta una fracción, y un grafo de llamadas responde "¿quién más usa esto?" en un solo viaje en lugar de una docena de greps. Orchemax ya parsea cada archivo que indexa, así que el grafo es un subproducto y no una segunda herramienta que instalar y mantener sincronizada.

Preciso en Go, heurístico en el resto#

Cada arista lleva una confidence, y ese número es la parte honesta:

Confianza	Cómo se resolvió la arista
`1.0`	El resolvedor de Go acertó un import, o el propio archivo
`0.7`	El resolvedor de Go acertó un tipo receptor
`0.4`	El tokenizador genérico acertó un `Name(` suelto contra la tabla de símbolos del mismo lenguaje

Así que Go es preciso y los otros veintiocho lenguajes langspec son heurísticos: una arista 0.4 es una llamada plausible, no probada. Un nombre que no resuelve a ningún símbolo indexado se descarta en vez de guardarse, así que un recorrido nunca cae en una arista colgante.

  fuente Go ----> resolvedor go/ast ---> aristas en 1.0 / 0.7
  otros leng. --> regex langspec     ---> símbolos, luego aristas del tokenizador en 0.4
                     |
                     v
              tabla symbol_refs  --> trace_path / impact / architecture

Qué no ve#

El índice ve símbolos con firma: funciones, tipos, métodos, clases. Es ciego a constantes, nombres de tabla, banderas de esquema y cualquier nombre que viva dentro de una cadena. Para eso, grep sigue siendo la herramienta correcta. Un resultado vacío es una respuesta real, no una falla: significa que no hay coincidencia, así que puedes crear la cosa localmente — pero no inventes un duplicado de un nombre que ya sabes que es compartido.

Cómo se relaciona con el resto#

El índice es el mismo que llena la ley del código compartido: alcance shared para símbolos etiquetados, local para todo lo demás. La búsqueda responde solo shared; el grafo lee ambos.
code_snippet y trace_path registran los bytes que devolvieron frente al tamaño del archivo que reemplazaron. Esos totales salen como un bloque graph en orch usage, libre de contenido.

Aquí no hay nada que ejecutar#

El grafo se consulta, no se construye: registrar e indexar una carpeta lo llena. orch index vuelve a escanear todo el workspace — cada proyecto registrado y cada ruta compartida, y orch inventory contrasta esas carpetas con lo que el índice realmente tiene.