kivgraph / internal
AGENTS.md21 starsChanged 3 months agoApache-2.0View on GitHub
Estas reglas se suman a las de AGENTS.md en la raíz del repositorio, que se leen siempre. Una instrucción de este archivo puede añadir restricciones; nunca puede relajar un contrato de integridad, compatibilidad o verificación declarado en la raíz. El camino Rust tiene su propio archivo en internal/rustloader/AGENTS.md y la superficie MCP el suyo en internal/mcp/AGENTS.md. - Un método cuyo receptor no tiene nombre -el de una interfaz anónima, sea la de var _ interface{ ... } = x o…
Where files are headingNew AGENTS.md files have more rules about keeping secrets out of the code, and fewer about code style.
Of the AGENTS.md files we read, the 32,671 first seen in the last six months, against the older ones: the kind of rule that gained most share, and the kind that lost most. About files like this in general, not this one, and an estimate, since a kind is a pattern in the words.
In this repository19 other files it gives its agents.
- AGENTS.mdAGENTS.md
- benchmarks/AGENTS.mdAGENTS.md
- landing/AGENTS.mdAGENTS.md
- ts-worker/AGENTS.mdAGENTS.md
- web/AGENTS.mdAGENTS.md
- benchmarks/CLAUDE.mdCLAUDE.md
- CLAUDE.mdCLAUDE.md
- internal/CLAUDE.mdCLAUDE.md
- landing/CLAUDE.mdCLAUDE.md
- ts-worker/CLAUDE.mdCLAUDE.md
- web/CLAUDE.mdCLAUDE.md
- adding-a-languageSkill
- autofixSkill
- code-reviewSkill
- merging-pull-requestsSkill
- opening-pull-requestsSkill
- publishing-releasesSkill
- running-testsSkill
- writing-blog-postsSkill
The file
We split this AGENTS.md into the rules it gives an agent
5 rules. About 0 are common, 3 are distinctive, and 2 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 16
No hay camino hasta él desde el scope del paquete, así que no obtiene objectpath y su identidad cae al nombre cualificado, que sin dueño es …
- Very specific: line 62
Toda pasada es una reconstrucción completa: No hay camino incremental: indexer.Full es la única entrada, kivgraph index prepara el proyecto …
- Distinctive: line 153
No leer ni servir consultas MCP directamente desde LadybugDB cuando el contrato exige el HotSnapshot publicado.
- Very specific: line 155
No mezclar el esquema experimental 001-synthetic con el canónico 002.
- Distinctive: line 392
No hay cerrojo entre procesos y no se lee antes de escribir.
≈ “Common” is an estimate: at least 1 in 5 of the 41,581 AGENTS.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Instrucciones del motor (internal/)
Estas reglas se suman a las de AGENTS.md en la raíz del repositorio, que se
leen siempre. Una instrucción de este archivo puede añadir restricciones; nunca
puede relajar un contrato de integridad, compatibilidad o verificación
declarado en la raíz.
El camino Rust tiene su propio archivo en internal/rustloader/AGENTS.md y la
superficie MCP el suyo en internal/mcp/AGENTS.md.
Carga de Go y workspaces
- Un método cuyo receptor no tiene nombre -el de una interfaz anónima, sea la
de
var _ interface{ ... } = xo la de una asercióny.(interface{ M() })- no es direccionable y nunca entra al grafo, igual que unlocal Nde Rust. No hay camino hasta él desde el scope del paquete, así que no obtiene objectpath y su identidad cae al nombre cualificado, que sin dueño es el nombre del método a secas: dos declaraciones así en un paquete derivan una sola clave desde dos ficheros, y unSymbolcon dosFileque lo declaran es lo que prohíbe la multiplicidad deDEFINES.go.include_testslo hacía aparecer porque un fichero de test es el segundo sitio donde se escribe esa interfaz. internal/indexer.Fullcarga Go mediante los patrones de paquetes producidos porDiscoverGo; no sustituirlos por./..., porque lasexclusionsconfiguradas deben seguir siendo efectivas durantego/packages.- Los tags de build con los que se carga Go vienen de
go.build_tags. Un directorio cuyos archivos excluye esa configuración no es un fallo del índice: se declara comoUNRESOLVEDcon razónPACKAGE_NOT_BUILDABLEy la pasada continúa. Cualquier otro diagnóstico del cargador sigue abortándola. Indexar este repositorio exige el tagladybug. - Ante el fallo de un repositorio entero hay dos contratos, y cuál aplica
depende del lenguaje. Go y Rust registran una fila
UNRESOLVEDsin archivo -MODULE_NOT_LOADED,WORKSPACE_NOT_LOADED,ANALYZER_UNAVAILABLE- y la pasada continúa: el grafo se publica declarando el hueco, y toda respuesta sobre ese repositorio sale comoLOWER_BOUND. TypeScript, Python y Dart devuelven error -indexSemantic,indexTypeScriptPackage- y la pasada aborta sin publicar, así que no se sirve ninguna respuesta sobre un repositorio que no cargó. Las dos formas son honestas y ninguna afirma una ausencia; sólo la primera es medible desde un grafo servido, y por eso es la única quebenchmarks/tool-honestyejercita. Que la fila no lleve archivo es el contrato, no un detalle:hotsnapshot.UnresolvedScopesselecciona exactamente las filas cuyo archivo no está puesto, así que una que ganara uno dejaría de acotar su repositorio y las preguntas sobre él volverían a decirCOMPLETEsobre un hueco. go/typesviaja enlazado en el binario: Kivgraph solo comprueba tipos hasta la versión del lenguaje del toolchain que lo compiló. Un módulo registrado por encima de ese techo se rechaza engoworkspace.BuildPlannombrando repositorio, módulo y versión; nunca se deja que elgo.worksintético escale el toolchain y reviente la carga de todos los repositorios dentro de la biblioteca estándar. El techo esmajor.minor.- El
go.worksintético resuelve una sola lista de build para los módulos que usa, así que el plan se parte en grupos independientes: dos módulos solo comparten workspace cuando uno alcanza al otro porrequire, porreplaceo por ungo.workdel repositorio indexado. Un módulo que no alcanza a ningún otro se carga en modo módulo, sin workspace, y los ficheros sintéticos que sobran se retiran con su.sum. La indexación sigue siendo hermética ygo.allow_networkes la única salida declarada cuando la MVS de un grupo selecciona un módulo ausente del caché local.
La pasada de indexación
- Toda pasada es una reconstrucción completa. No hay camino incremental:
indexer.Fulles la única entrada,kivgraph indexprepara el proyecto actual ykivgraph index --fullrecorre el registro configurado; cada pasada publica una generación nueva en vez de mutar la vigente. El delta --Update,Diff, el enrutado por planes de invalidación, las clases de cambio semántico y la mutación canónica incremental -- se retiró en el ADR 0057: no lo llamaba nadie, su techo medido era1,67xsobre un pase de9,17 s, y publicaba sin correrintegritynigolden probes. Lo que hace barata una reindexación es la caché de hechos, no un delta. - El análisis de la pasada es concurrente: cada módulo Go y cada paquete
TypeScript es una unidad independiente. El merge sigue el orden de las
unidades, nunca el de finalización, así que el grafo publicado no depende de
cómo se planificó el trabajo -- dos pasadas del mismo corpus producen hechos
idénticos byte a byte, y eso es lo que hay que verificar al tocar esta zona.
Los presupuestos son distintos por tipo:
go.maximum_loadsacota las cargas Go porque cada una sostiene un universo de tipos completo, ytypescript.maximum_workersacota los procesos del worker. El primer fallo cancela el resto. - Un módulo Go que el cargador no puede leer no tumba la pasada: no publica
hechos -- no serían de fiar -- y se declara como
MODULE_NOT_LOADEDcon los diagnósticos observados. Un repositorio cuyas dependencias nadie descargó no decide si los demás tienen grafo. - Cada tipo de unidad drena su propia cola, la más pesada primero, con tantos trabajadores como permita su presupuesto y nunca más que unidades tenga. El peso es una estimación sobre los archivos que la unidad leerá, nunca un hecho del grafo: una pasada termina cuando termina su unidad más lenta.
- Los hechos de todas las unidades se fusionan en una sola pasada
(
facts.MergeAll), no una unidad contra el acumulado: una fusión par a par vuelve a deduplicar, copiar y reordenar el grafo entero en cada paso, que es cuadrático en su tamaño. La identidad con la que se deduplica es una tupla comparable, no una cadena unida por separadores: una cadena hace ambiguo un nombre que contenga el separador, y aquí la deduplicación es lo único que decide si dos hechos son el mismo. - Una petición de indexación se construye en un solo sitio,
indexing.OptionsFromConfig: el llamador sólo añade lo que la configuración no decide -repositorios, directorio de trabajo, versión del resolver y los sinks de progreso-. Construirla dos veces es cómoindex_projectacabó sin nombrar ningún campo de Rust y fallando con «the Rust analyzer command is required» sobre la misma configuración que el CLI indexaba sin problema. Su resultado informa de los contadores de los seis lenguajes: un lenguaje ausente del informe se lee como un lenguaje sin código. - Un nombre de paquete TypeScript declarado por varios manifests es una
ambigüedad, no un repositorio roto: ningún manifest lo provee, ambos salen
del registro y se declara
AMBIGUOUS_PACKAGE_PROVIDER. Es el mismo trato que recibe un módulo Go con varios proveedores. - La indexación TypeScript procesa providers
package.jsonnombrados conProjectPathresuelto; pasa ese path al worker en cada invocación y omite manifests sin proyecto en vez de adivinar eltsconfigde la raíz. - Una ruta que el motor TypeScript resuelve llega con su grafía canónica, en
minúsculas cuando el filesystem pliega mayúsculas. Se corrige en la frontera
con
enginePathantes de indexarla, compararla o emitirla; nunca conrealpath, que resolvería los enlaces denode_modulesy cambiaría los hechos.
Caché de hechos
- La caché de hechos (
indexing.fact_cache) guarda una entrada por unidad de análisis con la lista de todo lo que la unidad leyó y su huella; servirla exige revalidar esa lista entera. Una entrada nunca se sirve a otro analizador: su identidad es el contenido del ejecutable, la respuesta dego env, el contenido del worker TypeScript, los build tags,include_testsygo.allow_network. Un módulo que el cargador no pudo leer no se guarda jamás, porque su fallo depende del caché de módulos y ninguna huella del código lo describe. Ver ADR 0030. - La procedencia de un repositorio -commit, rama, sucio- no es un hecho que
produzca ningún análisis: la estampa la pasada al fusionar, desde el registro
que se le dio, y ninguna unidad la escribe. Dentro de la entrada de caché se
volvía rancia en cada acierto, hacía que el commit publicado dependiera de
qué unidad fallara, y abortaba
verifypor un commit que no tocó un fichero. - El lockfile se busca desde la raíz del repositorio registrado hacia arriba y
se registra la cadena entera.
node_modulesno se recorre -es función del lockfile-, así que un lockfile que no se encuentra deja esa dependencia sin ningún control: en un monorepo pnpm vive por encima de los repositorios registrados. - Una entrada registra el nombre de lo que hay que volver a medir, nunca el valor medido: una entrada cuyo nombre lleva su propio valor se compara consigo misma y no puede invalidar nada.
- Un nombre de paquete que hoy no provee nadie es una dependencia con huella
absent, no la ausencia de una dependencia. Sin eso unUNRESOLVEDse serviría para siempre y nunca se convertiría en la arista que le toca. - Al tocar la caché se verifica con
fact_cache: verify, que analiza todo y aborta la pasada si una entrada discrepa del análisis. Comparar dos pasadas con caché no demuestra nada.
Grafo canónico y LadybugDB
- El código que usa la biblioteca nativa se compila con el tag
ladybug. - La pareja de versiones de LadybugDB y del binding Go debe provenir de la
fijación versionada y verificarse mediante
scripts/fetch-ladybug.sh. - Validar el grafo canónico antes de publicarlo. Una generación inválida nunca
puede convertirse en
CURRENT. - No leer ni servir consultas MCP directamente desde LadybugDB cuando el contrato exige el HotSnapshot publicado.
- No mezclar el esquema experimental
001-syntheticcon el canónico002. - Los iteradores
VisitRepositories,VisitPackages,VisitFiles,VisitSymbols,VisitEvidenceyVisitEdgesentregan copias por valor y no exponen slices internas; sus rangos son half-open y cancelables. NewGraphSnapshotcopia toda entrada mutable y eso es su contrato: el llamante puede seguir mutando lo que pasó, que es lo que hace el constructor. El lector de un fichero no lo necesita y no lo hace:readSnapshotllama al constructor interno cediendo la propiedad, porque susdecode*asignaron cada slice desde los bytes mapeados una sentencia antes y nadie más puede nombrarlos. Copiarlos producía un gemelo verbatim y dejaba el original de basura --20,8 MBsobreworkspace, medidos enbenchmarks/snapshot-heap, con los bytes vivos idénticos. Lo que hace segura la cesión es que ningún decodificador alía el mapa: los cinco usanmakey copian campo a campo. Quien escriba uno que devuelva una vista sobredatarompe esto en silencio.- La evidencia de una arista viaja al HotSnapshot sin su posición:
hotsnapshot.EvidenceRecordlleva clave, los dos ficheros, clase y procedencia, y el vano observado se queda en el grafo canónico. Así que ninguna tool puede abrir el texto que justifica una arista, en ninguno de los seis lenguajes: una fila defind_referencesusa el rango del símbolo y suevidence_kindsale de la procedencia. Es un hueco declarado, no un defecto a arreglar de paso: proyectarlo sube la versión del formato de filas del snapshot -- una superficie de compatibilidad-- y hoy ningún consumidor lo pide. Quien añada unevidence_keya un lenguaje debe saber que completa el contrato canónico y no cambia ninguna respuesta. CanonicalColumnsreconstruye el esquema canónico completo en cada llamada, así que las columnas de una tabla se resuelven una vez por tabla y nunca por fila. El grafo tiene una arista por referencia del corpus.- El scan canónico lee en chunks de Arrow, no valor a valor: un
Symbolson dieciséis cruces de cgo por fila y el grafo tiene una fila por declaración del corpus.scanCanonicalTuplespermanece como implementación de referencia y el test compara los dos lectores campo a campo -- un decoder de punteros equivocado produce un grafo que parece correcto, así que no se toca la ruta columnar sin ese oráculo. - El motor escribe un
NULLde cadena con los offsets0..0, que no son monótonos: el rango de datos de una columna es el más ancho sobre sus filas, nunca el que va del inicio de la primera al final de la última. - Una apertura de sólo lectura del grafo canónico recibe un buffer pool
proporcional a ese grafo -el doble de su tamaño, entre 256 MiB y 2 GiB-, nunca
el 80 % de la memoria del sistema que da el motor por defecto: un scan lee cada
página una vez y cierra. Una apertura de escritura conserva el defecto, que es
la caché que un
COPYde millones de filas necesita. - El catálogo de
canonical_integrity.goes la lista que la capa nativa usa para validar una arista. Una procedencia nueva que no entre ahí pasa todos los tests sin el tagladybugy revienta la integridad al publicar; el guardia que lo impide vive encanonical_catalog_test.go, sin tag. - Un upgrade de schema incompatible debe detectar la versión, respaldar y
verificar la generación activa antes de reconstruir desde repositorios fuente.
Solo una generación candidata que pase integridad y validación puede cambiar
CURRENT; un rollback debe comprobar los digests del backup. - Un rollback de versión debe cubrir restauración válida y rechazo fail-closed
ante digest ausente o divergente; si falla la validación,
CURRENTno cambia.
Generaciones, publicación y snapshots
kivgraph ui, ykivgraph servecuando contesta él mismo, siguen la generación publicada y republican cuando el punteroCURRENTavanza, sin coordinarse con nadie --SnapshotStore.Publishsolo acepta una generación estrictamente más nueva. Unindex --fullen otra terminal no puede dejar a un servidor sirviendo un grafo que ya no existe en disco. Unserveque hace de relé no abre store, ni seguidor, ni resync: no tiene grafo que seguir, y el que contesta es el demonio.- La publicación de una generación toma un
flocksobre el propio store. El mutex delStoresólo ordena las goroutines de un proceso, y un directorio de estado lo comparten unindex --full, unindex_projectde un cliente y el resincronizador de un servidor: sin él dos pasadas se pisan. Un candidato<id>.tmpque exista mientras se sostiene el lock es basura por construcción -el kernel seguiría sosteniéndolo por su escritor si viviera- y se retira. Rechazarlo convertía una pasada muerta -un OOM, una terminal cerrada- en un store inservible para siempre, porque todo intento posterior deriva el mismo identificador y choca con él. El lock no espera: una reconstrucción dura minutos y bloquear parecería un cuelgue, así que el perdedor recibeErrPublishInProgress. Para el seguidor eso no es un fallo, es exactamente lo que el lock existe para producir. - Tras un
cleancompleto la numeración vuelve a000001, ySnapshotStore.Publishsolo acepta una generación estrictamente más nueva: un servidor vivo conserva el grafo que ya no existe y no instalará ninguno más. El seguidor lo declara una vez y el comando avisa de reiniciar. - Tras publicar un snapshot se llama a
rebuild.ReturnBuildMemory: es el único momento en que el transitorio de la construcción está muerto -publicado, o descartado porque otro publicador ganó- y un servidor no tiene nada que hacer hasta la siguiente petición. Devuelve las dos mitades: el arena de Go condebug.FreeOSMemoryy el asignador nativo connativeheap.Return. La segunda no es un detalle: el heap de Go aparca entre 2,4 y 4 MB por encima del snapshot vivo en cada construcción, así que lo que hacía crecer a un servidor no era suyo. No se fijaGOMEMLIMIT, que el hijo de la pasada heredaría del entorno -indexing/subprocess.gono fijacommand.Env- y que en el lado de Go no tendría hueco que cerrar. Ver ADR 0044. - La memoria del motor es de libc, no de Go, y ninguna métrica de
runtimela ve. glibc da una arena por hilo que compite y la hace crecer antes de reutilizar nada, así que cada reconstrucción conserva otra arena hasta que saturan. Medido endevlabssobre un grafo de 189 MB, cuatro construcciones: con sólo el scavenge de Go el RSS va de 309,5 a 511,1 MB -67 MB por construcción-, y devolviendo también el nativo se queda en 241,5-249,6 MB, sin coste en tiempo. Acotar las arenas desde el proceso no sirve y está medido:malloptdespués de arrancar no mueve lo que ya vive en arenas secundarias. - Una generación lleva su HotSnapshot en
snapshot.kvsnap, y un servidor lo lee en vez de derivarlo del grafo canónico:rebuild.LoadOrBuildSnapshotes la puerta, y las tres rutas que instalan una generación -el arranque deserve, el seguidor y el padre de una pasada- pasan por ella. Lo que prueba que el fichero pertenece a esa generación essnapshot.content.sha256, el digest del grafo que el fichero contiene, repetido en su cabecera. No essnapshot.sha256, que digiere los contadores por tabla y por eso no distingue dos grafos de la misma forma: medido sobreworkspace, dos indexados cuyos grafos diferían en 288 filas dieron unsnapshot.sha256idéntico byte a byte, así que un fichero derivado de uno se aceptaba como del otro. El de contadores conserva su trabajo, que es la comprobación barata delRollback. Ninguna pasada muta una generación en sitio, así que un digest que no cuadra significa que el fichero es ajeno, rancio o corrupto. Escribirlo es una economía y nunca una precondición -- un fichero ausente, ajeno, rancio o corrupto cuesta una derivación, se declara en el informe y jamás una respuesta. Una generación publicada antes de que el registro existiera no lleva ninguno: eso esErrNoRecordedGraphDigest, de la misma clase que la ausencia, y contarlo como fallo pondría eldoctoren rojo en cada instalación al actualizar. Medido endevlabs: 253-255 MB de RSS y 787-836 MB de pico derivando, contra 150-152 MB y 264-269 MB leyendo. Ver ADR 0045 y ADR 0061. doctorhace las dos preguntas, y son distintas.snapshotderiva el snapshot del grafo canónico y nunca lee el fichero: informa de si este grafo todavía puede convertirse en snapshot, y leer un fichero escrito cuando el grafo estaba sano contestaría otra pregunta, y la contestaría tranquilizando.snapshot.publishedes la otra mitad: dice si el fichero se puede usar, o por qué un servidor tendría que derivar. Sin ella, un servidor que deriva el grafo entero en cada arranque es indistinguible de uno que lo lee, y eso costó dos veces mientras esto se construía.Dos servidores sobre la misma generación comparten el fichero. Medido con dos
servesobreworkspace--123.531símbolos,98.773.720bytes:94 MBdemapped filelimpio, una sola copia, y44,5 MBsucios por proceso. Con cuatro clientes son272 MBcontra los692 MBde la línea base sin compartir, un39,3 %. Lo que sigue siendo privado son las tablas decodificadas; lo compartido es el arena de cadenas, que es la parte grande.internal/procstatrepartePssyShared_Cleanen Linux y declara que darwin no puede: ahí el reparto sale defootprint, que no es la misma cantidad, así que las dos cifras no se comparan entre sí. En Linux, medido porbenchmarks/shared-snapshotsobre161.819símbolos: la cuota dePssdel brazo mapeado sobre el derivado es0,498con dos servidores,0,416con cuatro y0,372con ocho -- cae en cada paso, que es la propiedad, porque la parte compartida se reparte entre más procesos. Lo privado sale plano en614 Bpor símbolo,~95 MBpor proceso en ese corpus.Los dos umbrales originales de
LUQUE-2006no se cumplían --0,416contra≤0,40y95 MBcontra≤60 MB--, y lo que la medición mostró es que el problema eran los umbrales: uno era una propiedad del número de clientes y el otro un número de un corpus más pequeño. Están reescritos como propiedades. Mapear también las tablas sigue sin pedirlo ningún número: lo que ahorraría son esos614 Bpor símbolo, y el arranque --13x-- ya lo da el mapeo del arena.- El fichero publicado se mapea y el mapeo se conserva, porque la tabla de
cadenas lee sus valores en sitio en vez de copiarlos -- unos cincuenta megas
sobre el corpus real. Las demás tablas se decodifican a structs y sí se copian.
Eso hace que el mapeo tenga que vivir tanto como el snapshot, y su liberación
va atada a la inalcanzabilidad del
*GraphSnapshotconruntime.AddCleanup, nunca a unClosepúblico:Publishdeja el snapshot anterior como basura mientras alguien lo lee, y desmapear ahí no da un error, da unSIGSEGV. Lo que hace todo esto seguro y tiene que seguir siendo verdad: una tabla con arena prestada copia toda cadena que entrega, así que ninguna respuesta puede sobrevivir a las páginas de donde se leyó. Hay dos guardias, y los dos fallan si se retira la copia: uno compara direcciones -- comparar los bytes pasaría igual--, y el otro libera el mapeo a mano con un lector sosteniendo lo que leyó, y reportaSIGSEGVen vez deok. Un tercer test, el que borra el fichero y recorre el grafo entero, cubre que un mapeo sobreviva a su ruta. - La tabla de cadenas resuelve
Lookuppor búsqueda binaria sobre los ids ordenados por su valor, no con un mapa: eran 20,45 MB por proceso contra 1,9 MB, yLookupse llama una o dos veces por consulta. El orden lo lleva el fichero en su propia sección -es derivado y determinista, así que el escritor ordena una vez-, es opcional en las dos direcciones, y se valida exigiendo valores estrictamente crecientes: es la única sección cuya corrupción sería silenciosa, porque un orden válido de otra tabla sigue contestando con el id de otro valor. - El layout del visor es una proyección derivada del
HotSnapshot: usa coordenadas enteras deterministas, contención repository/package/file/symbol y un grid espacial con overflow acotado; nunca muta el snapshot ni ejecuta force simulation global. - El layout equilibra cada rejilla por defecto (
Columns: 0) para que el mundo publicado quede aproximadamente cuadrado; una anchura fija lo convierte en una tira ilegible cuando crece el número de repositorios. - El payload binario
LGVBdel visor es versionado (v2), little-endian y limitado a32 MiB; lleva una sección de etiquetas con el nombre de cada nodo, el servidor valida magic, versión, offsets, longitudes ysnapshot_idantes de servirlo, y los errores de incompatibilidad son códigos estables.
Configuración y registro
- El vocabulario de lenguajes es
config.SupportedLanguagesy se valida al escribir el registro, no sólo al indexar:initno acepta lo que la pasada rechaza. - Un ajuste de la configuración vale exactamente lo que el código implementa.
indexing.generated_filessólo aceptaincludeyindexing.unresolved_referencessóloretain, porque eso es lo que la pasada hace: aceptar otra palabra promete un comportamiento que no existe y convierte una errata en una configuración silenciosamente distinta de la que se leyó. - Una configuración escrita fuera de la ubicación por defecto es autocontenida:
su estado, su caché y su registro cuelgan de su propio directorio. Un
--configen/tmpque apuntase al estado real publicaría generaciones sobre el grafo que venía a dejar en paz. - Los nombres de repositorio se comparan exactos. El nombre es un identificador, nunca un componente de ruta, y las stable keys que lo llevan distinguen mayúsculas: dos repositorios que sólo difieren en el caso son dos repositorios y tienen que poder registrarse con su nombre real.
- Toda ruta de estado nueva se reubica en
stateBesideConfig, no sólo se añade aDefaultConfig. Es lo que hace autocontenida la regla de arriba: una ruta que se olvide ahí manda su contenido a la instalación real desde una prueba bajo/tmp.logging.event_log_pathes la última que entró.
Servidores HTTP, assets y procesos
kivgraph uies opt-in y sirve solo elHotSnapshotpublicado por HTTP read-only. Su bind por defecto es0.0.0.0:7777: el grafo se indexa donde están los repositorios y el visor se mira desde otra máquina, así que un default loopback obligaba a editar la configuración en el caso normal. La guarda es entonces la advertencia, y por eso no es decorativa: todo bind que no sea loopback registra qué se expone -rutas de repositorio y de fichero, nombres y firmas de símbolos- y con qué se cierra. El endpoint no lleva autenticación; restringirlo es--addroweb.address.kivgraph serveno escucha en ningún puerto, y esa es la parte que no cambia:webapi.Runes dueño del único listener y ejecuta un cierre graceful acotado al cancelar el contexto. Lo que sí hace desde el ADR 0084 es conectarse como cliente al demonio cuando hay uno: su entrada sigue siendo STDIO -- el manifiesto.mcpbno tiene campo para una url y una entradaurlen un fichero commiteado llevaría el token--, pero el servidor que contesta pasa a ser el demonio. Sin demonio alcanzable contesta él mismo, igual que antes, yKIVGRAPH_SERVE_IN_PROCESSfuerza ese camino. El relé vive eninternal/relayy no eninternal/mcp, que es donde el ADR lo esperaba:internal/daemonimportainternal/mcp, así que un relé que necesita unEndpointno cabe ahí sin un ciclo.internal/webassetssirve solo la copia generada deweb/distcuando la distribución se construye con el tagwebassets; los binarios sin tag devuelven un fallback visible503en vez de servir archivos no declarados.- La enumeración de procesos vive en
internal/procstat, el único lugar que lee estadísticas de proceso del sistema operativo, con un fichero por plataforma:/procen Linux ykern.proc.allmáskern.procargs2en macOS. Sólo se ven los procesos de este usuario, que son exactamente los que se podrían señalar; una plataforma que no sabe enumerar devuelve error, no una lista vacía, y0significa desconocido. internal/eventloges el registro durable de lo que pasó: una pasada, una llamada de tool, el ciclo de vida de un servidor. Es un fichero JSON-lines de solo-añadir, y esa forma es la que lo hace seguro para los varios procesos que lo escriben a la vez: un registro es una sola escritura de mucho menos que un buffer de tubería sobre un descriptorO_APPEND, que POSIX mantiene entera. No hay cerrojo entre procesos y no se lee antes de escribir; añadir cualquiera de las dos cosas no compraría nada. Ver ADR 0049.- No es una API. Es estado derivado y no lleva versión de esquema: borrarlo pierde historia y nada más. Un lector salta una línea que no parsea en vez de fallar la lectura, porque el fichero lo escriben varios procesos y uno puede ser de una versión que conoce campos que otra no.
- Un sumidero que no se puede abrir degrada con un aviso, nunca falla el
trabajo que describe. Un
*eventlog.Writernulo descarta, así que ningún productor lleva una rama para ese caso; yAppendno devuelve error por la misma razón. - La medición por tool ya existía y sigue donde estaba:
tools.observees el único punto por el que pasan las nueve tools de consulta, ymetrics.Registryacumula sus atómicos para quegraph_statuslos lea de vuelta. Lo que se añadió es un segundo canal lateral,metrics.QueryRecorder, simétrico con el puente OpenTelemetry: el registro no puede ser la fuente de un comando porque muere con el proceso.QueryRecordercorre dentro del camino caliente de una llamada, así que no puede bloquear. index_projectrecibe observadores variádicos como todoRegister*deinternal/mcp/tools. Los tuvo tarde, y mientras no los tuvo era la única llamada que un cliente podía hacer que ningún contador veía -- justo la que cuesta minutos.
Plataforma
- En macOS, la inspección de locks de LadybugDB nunca abre la base: POSIX
libera todos los locks de registro de un proceso al cerrar cualquier
descriptor sobre el archivo, así que un
fcntl(F_GETLK)desbloquearía el motor. Se enumeran descriptores conlibproc. - El watcher declara su contrato por backend. Bajo
kqueueun archivo creado y escrito de una vez llega como un únicoCreate, y el backend consume un descriptor por archivo vigilado: un árbol que excede el límite falla enNewnombrando el límite, nunca vigila un subconjunto en silencio. - La política que rechaza rutas con componentes symlink no se relaja para
acomodar
/varni/tmpde macOS. Los tests que alimentan la capa de workspace usaninternal/testsupport.TempDir.
Integraciones de clientes
kivgraph mcp installykivgraph skill installdetectan raíces locales conocidas cuando falta--target, muestran una selección interactiva de uno o varios clientes y conservan--targetpara automatización; nunca inicializan Kivgraph ni indexan repositorios.- La selección interactiva usa Bubble Tea y Lip Gloss:
↑/↓oj/kmueven,spacealterna,a/nseleccionan todos/ninguno,Enterconfirma yq/Esccancela; respetaNO_COLORy no emite ANSI al redirigir la salida. - Los adaptadores externos validan JSON/TOML antes de modificarlo, rechazan
destinos symlink, escriben atómicamente con
0600y exigen--forcepara sustituir o retirar una entrada incompatible. Las entradas idempotentes no reescriben el archivo. - La skill canónica vive en
internal/integrations/assets/kivgraph/SKILL.md; los bundles deben incluirla bajoskills/kivgraph/SKILL.mdy enSHA256SUMS.
Verificación
gofmt -l <archivos-go-modificados>
go vet ./...
go test ./...Si el cambio toca LadybugDB nativo, make test-ladybug; PKGS acota la pasada
a un paquete. El procedimiento completo está en la skill
.claude/skills/running-tests/SKILL.md.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

