Las páginas sin traducir se abren en inglés y se indican como inglés.
Esta página es una traducción automática de la página en inglés, que prevalece. Machine-translated from the English page, which is authoritative.
Arquitectura del índice de código
Esta página es la vista interna del índice de código: cómo los archivos se convierten en fragmentos, símbolos y aristas, y cómo se mantienen actualizados los dos niveles. Lo que responde cada op, los lenguajes y su profundidad, y cómo leer as_of están en la
descripción general del índice de código y en
actualidad de los datos. La puesta en marcha (clones, backfills, los niveles del compilador)
está en operaciones del índice de código.
Objetivos y no objetivos
| Objetivos | No objetivos |
|---|---|
| Actualización por cada merge del nivel rápido a partir de un sondeo de un mirror bare local; sin webhook entrante. | Indexar un árbol de trabajo. Los cambios sin commit y sin push nunca están en el índice. |
| Aristas exactas de llamada, sobrescritura y herencia donde existe un indexador de compilador; heurísticas graduadas en el resto. | Ejecutar un compilador en el proceso del servidor. Los productores SCIP se ejecutan en subprocesos del proceso workers. |
| Ingesta idempotente: los mismos bytes producen las mismas filas y no cuestan ningún embedding. | Un host de código de propósito general. El índice son datos de referencia de solo lectura organizados por espacio de nombres. |
| Cada respuesta indica el commit y el nivel que leyó, y explica por qué una respuesta vacía está vacía. | Ocultar la obsolescencia. Se informa de un nivel retrasado. |
| Un lenguaje nuevo se incorpora sin reindexar los demás. | La misma profundidad para todos los lenguajes (lenguajes). |
Un espacio de nombres, una rama
Un espacio de nombres de código es una rama de un repositorio en un commit concreto. Tiene kind='code' en
loom.namespaces (code/app/index/registry.py, ensure_registered), no contiene
memorias y organiza cada fila code_* por (org, namespace). Loom mantiene un mirror git bare
por repositorio, una caché del remoto registrada en ClickHouse: code_ingest clona
uno que falte (o lo hace loom code init, con antelación) y lo actualiza con fetch en cada pasada.
server/code/app/index/gitrepo.py invoca git mediante shell; no tiene árbol de trabajo y no escribe
nada excepto fetch. Las ramas de un mismo repositorio comparten el mirror.
Una lectura de historial (blame_range, bisect, first_build, la comprobación de código de una lección) en un host
sin el mirror lo clona una vez en segundo plano
(server/code/app/index/mirrors.py, history_dir). Una lectura que nombra su op espera hasta
10 s por el clon que inició, o lo que quede del presupuesto de latencia de la op, lo que sea
menor; las demás responden no_git_mirror hasta que el clon termine. Tras el clon, se obtienen por sha y se fijan los commits de merge del ledger
que le faltan al clon: un merge hecho en una rama de staging
que el upstream ha eliminado desde entonces está en el mirror del worker (nunca se poda), pero no en un clon nuevo. Un mirror presente responde tal como está; uno al que le falta el head indexado
hace fetch de la rama en segundo plano. Un head que no es el de la rama (el head de un PR) no se obtiene.
Esto coloca una copia completa de cada mirror en cada host de servicio al que se consulte, lo cual es
la ventaja (cualquier host responde lecturas de historial tras un traslado o un scale-out) y el coste
(disco por host: el tamaño de un repositorio por cada uno). LOOM_CODE_HISTORY_CLONE_ON_READ=false
lo desactiva: solo clona el host del worker, y una lectura de historial en cualquier otro lugar responde
no_git_mirror.
Las entradas de repositorio provienen de dos fuentes, combinadas:
| Fuente | Leída por | Notas |
|---|---|---|
| Entorno | code/domain/index/repos.py |
LOOM_CODE_REPOS_JSON, o los ajustes escalares LOOM_CODE_*. |
loom.code_repos |
code/app/index/repo_registry.py |
Filas de autoservicio, según row_kind (abajo). El token de un remoto privado se almacena cifrado y nunca se devuelve. |
El row_kind de una fila de loom.code_repos indica de qué se trata:
page: una rama añadida desde la página. Conserva fuera de su espacio de nombres una entrada del operador, eliminada o no.access: la clasificación y la política de unión de una entrada del operador.'': una fila escrita antes de existir la columna, que se lee como la fila de acceso del espacio de nombres de una entrada del operador y como una rama añadida desde la página en cualquier otro caso.
configured_repos() lee una instantánea en proceso que se actualiza al arrancar, en cada pasada de ingesta y tras una adición. Hasta la primera lectura de la instantánea lanza RegistryUnread
(con autoservicio activado), ya que aún no se conocen las entradas que omite un espacio de nombres de página; los módulos que deciden el acceso leen config_entries(), que lista las entradas anteriores a esa
lectura sin ninguna legible por la organización (tests/unit/test_repo_snapshot_contract.py). Una op
que necesita la lista completa responde 503 en esa ventana; las lecturas de memoria, la búsqueda y
memory.for_file responden sin enlaces de código. Una llamada de código que no nombra espacio de nombres usa por defecto
LOOM_CODE_NAMESPACE solo cuando ningún miembro añadió ese espacio de nombres desde la página.
Retirar una entrada (code/app/index/retire.py) desactiva sus filas, ejecuta una saga de borrado sobre
cada tabla code_* del espacio de nombres y elimina el mirror cuando ninguna otra entrada lo usa
en el host que atendió la llamada; la limpieza de cada uno de los demás hosts elimina su propia copia.
Mirrors de git en cada réplica
Todo proceso que sirve puede responder una lectura de historial (blame, bisect, citas, superposiciones de PR, cobertura de commits), por lo que cada host mantiene sus propios mirrors bare (code/app/index/mirrors.py). Un mirror es una caché de su remoto: ClickHouse nombra el remoto y cualquier host puede reconstruir el mirror a partir de él.
- Warm-up. Al arrancar, cada proceso clona los mirrors de las entradas indexadas que le faltan,
LOOM_CODE_MIRROR_WARMUP_CONCURRENCYa la vez, cada uno tras una espera aleatoria de hasta 30 s, para que N réplicas que arrancan juntas no clonen todas desde GitHub al mismo tiempo. Los clones se ejecutan en segundo plano: la disponibilidad (readiness) no los espera. - El costo de un disco nuevo. Un host con un
LOOM_CODE_REPOS_ROOTvacío hace un clon bare completo de cada repositorio indexado (varios GB en uno grande) antes de que sus lecturas de historial respondan. El warm-up queda activado por defecto porque una réplica nueva debe construir sus cachés sin un operador; colocaLOOM_CODE_REPOS_ROOTen un volumen que sobreviva a un rollout para pagarlo una vez por volumen y no una vez por pod. Los clones son completos, no--filter=blob:none: un clon parcial obtiene cada blob que falta desde el remoto mientras se ejecutagit blame, lo que convierte una lectura de historial en una lectura de red y alcanzaría el remoto fuera del sandbox de trabajos de repositorio. - La compuerta. Toda lectura de historial pasa por
mirrors.history_dir, que devuelve el mirror o la razón por la que no hay ninguno. Hasta que el mirror existe, la lectura respondeno_git_mirror: cloning <entry>(o la razón por la que no se clonará aquí) en lugar de un error de git, e inicia el clon si no hay ninguno en curso.LOOM_GIT_HISTORY=nonedesactiva el historial en un host: esas lecturas respondenno_git_history. - El bucle del host. Solo el líder pregunta al remoto qué cambió (
ls-remotede las ramas extra y de las cabezas de PR). Lo que obtuvo su pasada está en ClickHouse: la punta de rama de cada entrada (clone_head), las cabezas de los PR abiertos (code_gh_items.head_sha) y los merges del ledger. CadaLOOM_CODE_MIRROR_FETCH_INTERVAL_S, cada host lee esos datos y hace fetch, por nombre, solo de las ramas y cabezas de PR que su mirror tiene en otro sha, más una página de merges del ledger que le faltan; un host que está al día no hace ninguna llamada de red. Las ramas extra no se siguen en los demás hosts: un clon nuevo trae todas las ramas que tenía el remoto, y los merges en ellas llegan por el ledger. Un proceso por host ejecuta la ronda de cada mirror, y todo fetch hacia un mirror (el de la pasada, el del bucle del host, el de una lectura) toma el.fetch-lockdel mirror; el fetch de la pasada también cuenta como la ronda del host para el intervalo. El mismo bucle ejecutagit gc --no-prunecuando corresponde y barreLOOM_CODE_REPOS_ROOT: mirrors, árbolescheckout-*y archivos de bloqueo de mirror que ninguna entrada activa nombra (incluidas las entradas restringidas) y clones a medias. No barre nada cuando no se puede leer el registro. - Sandbox. Un host sin el sandbox de trabajos de repositorio nunca clona ni hace fetch de una entrada añadida por un viewer con un remoto de red, tanto en la ruta de lectura como en el worker (
compiler_tier.unsandboxed_skip). - Merges que el remoto perdió. Un merge del ledger que el remoto ya no sirve ("not our ref" en dos llamadas, para que una sola negativa transitoria no cuente) se registra en el mirror (
loom-unpinned-merges), no se vuelve a pedir y se cuenta en/v1/health?include=mirrors(mirrors.unpinned_merges) y enloom doctor. - El líder también clona en segundo plano un mirror que falta, para que un clon largo no retenga las demás entradas de su pasada; una entrada indexada conserva su etapa en la tarjeta de Repositories mientras su mirror se vuelve a clonar en un host nuevo.
- Borrado. Los mirrors y los checkouts contienen contenido de repositorios, no contenido de memoria: el censo de borrado no los cuenta. Las copias de un repositorio eliminado desaparecen con el barrido en cada host.
/v1/health?include=mirrors incluye mirrors: cuántos de los mirrors de este host están ready y cloning, y los failed y absent contados por razón. Responde sin token, por lo que no nombra ninguna entrada. El uso de disco es el tamaño de todos los mirrors en todos los hosts: N réplicas guardan N copias.
Componentes
flowchart LR
GH["Git remote"] -- fetch --> BC[("bare mirror")]
BC --> CI["code_ingest<br/>(fast tier)"]
CI --> P["parse: treesitter.py,<br/>lang_* lanes"]
P --> CH["chunker.py"]
P --> ED["edges_treesitter.py,<br/>dependents.py"]
CH --> CC[(code_chunks)]
P --> CS[(code_symbols)]
ED --> CE[(code_edges)]
CI --> CF[(code_files)]
CI --> ST[(code_index_state)]
BC --> SD["code_scip_*_delta<br/>(compiler tier)"]
SD --> AP["scip_delta apply"]
UP["code.scip_ingest"] --> AP
AP --> CS
AP --> CE
CC -. "stub dim=0" .-> ER[code_embed_recovery]
ER --> CC
API["GitHub API"] --> PH[code_pr_history]
PH --> PRT[(code_pr_history<br/>code_pr_reviews<br/>code_gh_items)]
Nivel rápido: code_ingest
server/code/workers/ingest.py consulta cada LOOM_CODE_INGEST_INTERVAL_SECONDS;
code.refresh dispara una pasada desde CI. Por cada entrada, cada pasada:
- Obtiene el mirror y recorre los commits de primer padre desde la marca de agua
git_headencode_index_statehasta la punta, del más antiguo al más reciente, como máximoLOOM_CODE_INGEST_MAX_COMMITS_PER_PASS. - Reindexa exactamente los archivos modificados de cada commit (
ingest_fileencode/app/index/ingest.py): parseo, fragmentos, símbolos, aristas, guardas de llamadas, la fila del archivo, y un paquete de contexto y un resumen de revisión para el PR fusionado que el commit nombra. Luego avanzagit_head. Un fallo reejecuta desde el último commit completo. - Recorre con la parte
LOOM_CODE_INGEST_WALK_BUDGET_SHAREque queda: reparaciones de reconciliación y re-fragmentaciones del extractor (más abajo).
| Límite | Efecto |
|---|---|
LOOM_CODE_INGEST_MAX_PASS_SECONDS |
Duración de la pasada. |
LOOM_CODE_INGEST_PASS_BUDGET_FRACTION |
Tras esta parte la pasada no inicia unidades nuevas, guarda los cursores y devuelve partial: true. |
LOOM_CODE_INGEST_SECONDS_PER_FILE |
Predice el costo de un commit; un commit que se prevé que se exceda solo empieza como el primero de la pasada. |
LOOM_CODE_INGEST_SLICE_SHARE |
Lo máximo de la fase de commits que puede ocupar un commit demasiado grande antes de dividirse entre pasadas. |
LOOM_CODE_INGEST_LANES |
Entradas ingeridas en paralelo (por defecto 1, hasta 8). Los commits de una misma entrada siguen en secuencia. |
LOOM_CODE_INGEST_ROUND_FILES |
Archivos por ronda dentro de un commit; las lecturas se precargan en dos sentencias y las escrituras se agrupan en lotes. |
Los carriles ayudan porque un carril espera viajes de ida y vuelta a ClickHouse, no CPU.
Admisión. Un archivo se rechaza antes del parseo cuando coincide con la lista de denegación
(code/app/index/denylist.py, LOOM_CODE_INGEST_EXCLUDE,
LOOM_CODE_INGEST_IGNORE_FILE), es binario o supera LOOM_CODE_INGEST_MAX_FILE_BYTES.
Por eso coverage_floor: true en un grep significa todos los fragmentos admitidos, no todos los bytes.
Elección de un parser
ingest_parse.parse_for_ingest prueba estos en orden. El orden mantiene los tipos de archivo nuevos fuera del
sello del extractor:
treesitter.lang_for_path: el núcleo sellado (C/C++ con.hmediante la gramática de C++, Python, shell, SQL, doc, config). Despuésingest_parse._lane_languagereasigna los archivos CMake y las configuraciones TLC.- Manifiestos de Helm y Kubernetes entre los archivos de configuración (
lang_gotemplate,lang_k8s). lang_detect.detect_by_extension(LANG_BY_EXTENSION).- Un shebang, luego la detección de shell por nombres de Linguist y directivas de ShellCheck
(
lang_detect.detect_shell). - Archivos host (Dockerfile, Makefile, Jenkinsfile, YAML de CI) con
LOOM_CODE_HOST_ISLANDS(lang_hosts). - Fixtures de salida esperada, un fragmento sin embeddings por archivo (
lang_reference). - Cualquier otro texto, dividido en fragmentos sin símbolos (
lang_text).
El parser proviene de ingest_parse._PARSERS. Un fallo de ese parseo, incluida una gramática ausente
o un parseo de tree-sitter que supere code_parse_timeout_s o code_parse_memory_mb
(bounded_parse, un parseo a la vez), degrada a un archivo solo con fragmentos con
code_files.index_error establecido; code.index_errors lo informa; en cambio, una especificación TLA+ recurre
a su lector basado en regex. Un parseo que supere sus límites en cualquier otro lugar usa el respaldo de quien lo llama y no registra ningún error.
Los módulos de tree-sitter se importan de forma diferida, de modo que un servidor con los workers de código desactivados arranca sin los
extras de code.
Fragmentos
server/code/domain/extract/chunker.py corta unidades semánticas, nunca ventanas fijas:
| Fragmento | Contenido |
|---|---|
function |
El cuerpo de una función. Uno demasiado grande se divide en sentencias de nivel superior, cada parte con la firma como prefijo. |
class_skeleton |
Una clase con los cuerpos de los métodos omitidos. |
file_header |
Comentarios iniciales e includes. |
other |
El resto, agrupado. |
Los archivos sin árbol recurren a ventanas de líneas completas; los carriles sin gramática cortan según
sus rangos de símbolos (lane_units.span_chunks). El id de un fragmento es
uuid5("loom://code/{namespace}/{path}#{scope}@{sha16}"). Está direccionado por contenido, así que
un fragmento sin cambios conserva su id y su hash, y el paso de embedding lo omite sin consulta.
Los fragmentos idénticos dentro de un archivo reciben un sufijo ordinal.
Símbolos y aristas
El id de un símbolo es treesitter.symbol_id(qualified_name, signature): los primeros 128 bits de
SHA-256 sobre el nombre y una firma normalizada (espacios en blanco colapsados, valores por defecto
eliminados, de modo que las sobrecargas difieran). El nivel rápido, el conversor de SCIP y la ruta de lectura
lo llaman todos, así que ambos niveles asignan un símbolo compartido bajo un mismo id. Python y shell califican los nombres
por ruta de módulo, de modo que las muchas funciones main() de un árbol de pruebas siguen siendo distintas.
Las aristas del nivel rápido (edges_treesitter.py, tier='treesitter') se resuelven por nombre y
se califican:
| Confianza | Regla |
|---|---|
| 1.0 | Definición única en el mismo archivo |
| 0.8 | Método de la clase envolvente |
| 0.6 | Coincidencia única en la tabla de nombres de símbolos de todo el repositorio |
| ninguna | Ambigua o desconocida: sin arista; se registra en code_call_sites_unresolved |
Una arista errónea es peor que una ausente, por lo que code.callers informa cuántos sitios
deja fuera su conteo. Las llamadas a constructores (T x(...), new T, make_unique<T>) son llamadas
a T::T. Los módulos de tipo de receptor (cpp_receivers.py, py_receivers.py, ts_receivers.py,
go_receivers.py) enlazan las llamadas a miembros. Los tipos de arista son calls, includes, inherits,
overrides, uses_type, fixture_use, reads y writes.
Dependientes. Las aristas se resuelven contra una tabla de nombres de todo el repositorio, así que un commit que
agrega, elimina o cambia la firma de un símbolo modifica las aristas de archivos no tocados que lo nombran.
code/app/index/dependents.py vuelve a extraer solo las aristas de esos archivos en el mismo
commit, hasta LOOM_CODE_INGEST_DEPENDENTS_MAX_FILES. El excedente espera en
code_index_state (dependents_pending) y se drena mediante la reconciliación.
Embeddings y tablas de vectores
code_ingest genera embeddings de los fragmentos nuevos en línea, memoizados por hash de contenido (embed_reuse.py),
con texto acotado (embed_text.py). Con LOOM_CODE_CONTEXT_DESCRIPTION_ENABLED (activado por
defecto) un fragmento recibe una descripción de una línea generada por un LLM, antepuesta a su texto del embedding,
con el mejor esfuerzo y sujeta al presupuesto. Un fallo del proveedor deja un stub con embedding_dim = 0 que
code_embed_recovery completa, con respaldo por texto y marcado como envenenado tras
LOOM_CODE_EMBED_MAX_ATTEMPTS. Hasta que LOOM_CODE_READY_EMBED_COVERAGE de los fragmentos de un espacio de nombres
tenga vectores, code.search responde con sus ramas léxicas y lo indica.
| Tabla | La llena | Uso |
|---|---|---|
code_summaries |
code_summary (semanal, desactivado por defecto) |
Fichas de archivo y módulo para code.map, controladas por un hash de entradas, con PageRank de code_graph_stats. |
tablas del segundo modelo, code_chunks_prefix |
LOOM_CODE_VECTOR_TABLES; loom code vector-twin |
La rama vectorial preselecciona en el gemelo más pequeño y revalúa con los vectores servidos (prefix_twin.py). |
code_answers |
code.ask |
Caché de respuestas indexada por el embedding de la pregunta; se sirve solo si el hash de cada archivo citado está vigente. |
Las pasadas masivas dejan copias adicionales por clave hasta una fusión. code/app/index/compaction.py
ejecuta OPTIMIZE … FINAL en las tablas gemelas tras una pasada masiva. code_chunks se compacta
solo con loom code compact --table code_chunks --apply.
Nivel del compilador: SCIP
El nivel del compilador contiene símbolos y aristas con tier='scip'. El servidor nunca analiza
protobuf: un productor convierte la salida de SCIP a un delta JSON versionado
(scripts/scip_harness/scip_to_delta.py) y code/app/index/scip_delta.py
lo aplica. Por cada archivo afectado, la aplicación hace upsert de lo que emite el delta y marca como eliminadas (tombstone) las filas scip
del archivo que ya no emite; un archivo borrado se marca como eliminado por completo. Volver a aplicar un
delta produce el mismo conjunto activo.
| Productor | Lenguaje | Marca de agua | Workers | Cómo se ejecuta |
|---|---|---|---|---|
scip-clang |
C++ | scip_commit |
code_scip_full, code_scip_delta, code_scip_apply |
TU modificadas (y TU que incluyen cabeceras modificadas, con un límite) mediante run_delta.sh; code_scip_full inicializa el nivel y lo reindexa cada semana. |
scip-typescript |
TypeScript / JavaScript | scip_commit_ts |
code_scip_ts_delta |
Índice de todo el workspace en cada pasada, limitado por el conversor a los archivos de la ventana. |
scip-go |
Go | scip_commit_go |
code_scip_go_delta |
Una compilación por módulo (run_go_monorepo_delta.sh). |
scip-python |
Python | scip_commit_py |
code_scip_py_delta, code_scip_apply |
Delta por cada merge (run_python_delta.sh); la primera ejecución indexa el árbol. |
code/domain/index/compiler_tiers.py (TIERS) es la tabla única de marca de agua, etiqueta
y workers por productor; los manejadores de estado y el panel la leen. Un worker de delta
compara su marca de agua con git_head, mueve el checkout (haciendo fetch desde el mirror local,
no desde la red), ejecuta el productor en un subproceso y aplica el delta
por la misma ruta que usa code.scip_ingest. Una pasada cubre todos los merges desde la
marca de agua.
Un productor externo, como un trabajo de CI, puede subir un delta por partes con
code.scip_ingest; las partes se almacenan temporalmente en code_scip_batches / code_scip_parts y
las aplica code_scip_apply. Cada pasada del nivel del compilador toma un archivo de bloqueo por entrada en
LOOM_CODE_SCIP_LOCK_DIR y un lease de ClickHouse, de modo que una reindexación completa y un delta nunca
se ejecutan a la vez sobre una misma entrada. loom code scip-full reconstruye
el nivel de C++; loom code scip-delta ejecuta una pasada de delta.
Cuando ambos niveles tienen la misma fila, las lecturas prefieren la fila del compilador, y cada respuesta
indica el nivel que leyó (scip o treesitter).
El sello del extractor
Los chunks direccionados por contenido y los ids de símbolo con hash dependen de la entrada, no del código que
produjo las filas, así que una corrección en el chunker nunca llegaría a una fila existente.
server/code/domain/extract/extractor_stamp.py cierra esa brecha. Calcula el hash de los tokens de código de
cada módulo del extractor (logic_tokens: sin comentarios, líneas en blanco ni docstrings, y con cada
import reducido a los nombres que enlaza, de modo que mover un módulo entre paquetes no mueve ningún
sello) más las versiones instaladas de las gramáticas selladas (STAMPED_GRAMMARS: la biblioteca base, C++,
Python, bash).
El sello se divide de dos maneras para que un cambio vuelva a derivar lo mínimo posible:
-
Por etapa (
STAGES:chunk,symbol,edge,guard;STAGE_MODULES). El sello de una etapa cubre sus módulos y los de las etapas que lee (STAGE_INPUTS).Módulo modificado Etapas afectadas chunker.pychunkedges_treesitter.pyedge,chunk,guardtreesitter.py,lang_python.pytodas ( symbolalimenta al resto)call_guards.pyguard
- Por familia de lenguaje (
LANGUAGE_FAMILIES:python,shell,typescript,cpp,other;MODULE_LANGUAGES). Un cambio solo de Python sana los archivos.pyy deja C++ intacto. Los módulos de aristas de TypeScript (ts_receivers.py,ts_reexports.py,ts_config.py,ts_workspace.py) mueven solotypescript. Un módulo sellado que falta enMODULE_LANGUAGESmueve todas las familias.
Cada pasada compara los sellos en ejecución con los de code_index_state. Una etapa afectada se
vuelve a derivar para cada archivo de esa familia en cada espacio de nombres indexado, en lotes
dosificados (LOOM_CODE_EXTRACTOR_RECHUNK_PER_PASS, interruptor LOOM_CODE_EXTRACTOR_RECHUNK_ENABLED).
Un sello registrado vacío se registra, nunca se actúa sobre él. Por tanto:
- un cambio de código en un módulo de
EXTRACTOR_MODULESreindexa todos los repositorios de las familias afectadas, lo que tarda horas en un despliegue grande; los comentarios y los docstrings se pueden editar libremente; - esos archivos están excluidos de los formateadores (
pyproject.toml), ytests/unit/test_code_extractor_stamp.pymantiene sincronizados la lista de exclusión y el inventario de módulos: un módulo deserver/code/domain/extract/que no esté en ninguna etapa debe figurar enNON_EXTRACTOR_MODULESde la prueba con su motivo; - modifícalos solo cuando cambie la extracción, y espera la nueva derivación tras el despliegue.
Los módulos de carril quedan fuera del sello. Los parsers de carril (lang_typescript.py,
lang_rust.py, lang_go.py, lane_units.py, …), sus gramáticas y los módulos de selección de archivos
(lang_detect.py, denylist.py) no lo mueven; los módulos de aristas de TypeScript
mencionados arriba son la excepción. Una corrección de carril se aplica con loom code backfill --paths-file
sobre los archivos de ese lenguaje.
Reconciliación
Las watermarks indican qué commits se recorrieron, no si cada fila está actualizada.
code/app/index/reconcile.py mide la deriva. Una fila de code_files incluye blob_sha
e indexed_commit. Un solo git ls-tree -r <head> marca una ruta como obsoleta cuando su blob
difiere, y como eliminada cuando no existe. Las filas sin blob recurren a un
git diff --name-only por cada commit distinto, hasta LOOM_CODE_RECONCILE_MAX_COMMITS.
La comprobación cada hora en code_ingest (LOOM_CODE_RECONCILE_ENABLED,
LOOM_CODE_RECONCILE_INTERVAL_SECONDS) vuelve a ingerir hasta LOOM_CODE_RECONCILE_HEAL_PER_PASS rutas
obsoletas mediante ingest_file; solo se generan embeddings del contenido nuevo. De forma manual: loom code reconcile --heal. El gauge loom.code.stale_files
informa el recuento.
Marcas de agua y cobertura
code_index_state (ReplacingMergeTree(version), con clave (org, namespace, state_key))
contiene git_head, las marcas de agua de SCIP por productor, los sellos del extractor, los cursores y
dependents_pending. El bloque as_of de cada respuesta y
loom.code.tier_lag_seconds{tier} se calculan a partir de estas filas y del mirror, no a partir del log de
un productor. La cobertura por commit (code/app/index/commit_coverage.py) es un
git merge-base --is-ancestor por nivel sobre el mirror, nunca una comparación de marcas de agua.
Lo que ven los llamadores está en frescura.
Historial de PR, backports y enlaces a trackers
| Tabla | Escritor | Contiene |
|---|---|---|
code_pr_history, code_pr_reviews, code_gh_items |
code_pr_history (GitHub REST, cursor sobre updated_at) |
PR fusionados con archivos, comentarios de revisión e issues. Un límite de tasa o un 5xx deja el cursor sin avanzar. |
code_context_packs, code_review_briefs |
code_ingest en el commit de fusión, o bajo demanda |
Paquete de contexto y resumen para el revisor de cada PR. |
code_backport_gaps |
code_backport_gaps (nocturno; requiere code_pr_history) |
Por cada PR de la rama principal con etiqueta de backport, una fila por espacio de nombres de rama de release: cubierto, pendiente, no afectado. |
code_test_map, code_symbol_stats, code_unit_risk |
code_graph_stats (semanal), loom code crossref |
Mapa de pruebas↔código fuente, fan-in de símbolos, riesgo por unidad. |
code_coverage_files |
code_coverage_import (diario), loom code coverage-import |
Por archivo fuente, los rangos de líneas que ejecutó una ejecución de cobertura por prueba. |
qa_link_candidates |
tracker_links (diario) |
Los PR fusionados principales por cada issue reciente, ordenados por BM25F, trazas de pila en el diff y menciones de cierre. |
qa_item_embeddings |
tracker_embed |
Vectores de issues y PR del tracker en la ventana de embeddings; claves y datos de filtro, sin texto. |
code.repo.set_source vincula un repositorio con sus trackers, en orden; el primero es el
principal, cuyos números son los números de issue y de PR del repositorio. Los enlaces son
la fila qa_binding de code_index_state y se leen por (org, namespace): el nombre de
un espacio de nombres de código se deriva del repositorio y la rama, por lo que dos orgs
pueden tener el mismo. LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON, del operador, se aplica
solo a los repositorios del propio operador (LOOM_CODE_REPOS_JSON o LOOM_CODE_REPO),
nunca a uno de autoservicio cuyo nombre coincida con un glob. Los workers del tracker leen
cada espacio de nombres a través de su propia fuente, de modo que las filas de un espacio
de nombres restringido nunca terminan bajo uno estándar. El contrato de registros está en
contrato de registros del tracker.
code.repo.add_branch escribe la fila qa_branch_of de la nueva rama con el nombre del
repositorio raíz (la fuente, o la raíz de la propia fuente cuando esta es una rama) cuando
esa raíz es un repositorio del operador, de modo que la rama de una raíz de autoservicio
nunca empiece a leer el mapa si el operador configura más tarde el nombre de esa raíz. Una
rama registrada cuya raíz es un repositorio del operador sigue los enlaces de ese
repositorio en el momento de la lectura, incluido el glob; una fila qa_branch_of sin una
entrada de autoservicio junto a ella no se sigue. Una fuente que no es un repositorio del
operador tiene su propia fila qa_binding copiada a la rama, incluso si estaba vacía. Una
fuente del operador es su propia raíz. Ambas filas se escriben leyendo primero las filas de
la fuente y dejando qa_branch_of al final, por lo que un fallo deja a la rama sin seguir
nada.
code.repo.remove vacía la fila, de las dos, que contenga un valor antes de la purga
desacoplada del espacio de nombres. Registrar un espacio de nombres vacía cualquier fila
que dejó uno eliminado con el mismo nombre y quita el nombre de la instantánea de su propio
proceso, de modo que el nuevo espacio de nombres no sigue a ninguno. Un qa_binding vaciado
se lee como borrado hasta que un administrador del tracker lo vincula. Un espacio de nombres
que no tenía fila qa_binding no recibe ninguna, así que el mapa del operador sigue
alcanzando una entrada del operador configurada con el mismo nombre. Una entrada del
operador configurada bajo un nombre eliminado no recibe esa limpieza: hasta que se ejecuta
la purga, lee la fila qa_binding del espacio de nombres eliminado cuando existe, es decir,
los enlaces antiguos tras una eliminación en la compilación N-1 y ninguno tras una en N. Los
demás procesos conservan las filas que leyeron hasta LOOM_CODE_REPOS_REFRESH_SECONDS.
Almacenamiento
| Tabla | Motor y clave | Notas |
|---|---|---|
code_files |
RMT(version), (org, namespace, path) |
Último análisis por ruta: lenguaje, blob_sha, indexed_commit, index_error. |
code_chunks |
RMT(version), (org, namespace, embedding_model, path, chunk_id), particionada por (org, namespace) |
Contenido, lexemes, vector. Índices de texto: 3-grama sobre lower(content), tokens sobre lexemes. |
code_symbols |
RMT(version), (org, namespace, tier, qualified_name, symbol_id) |
Definiciones con firma, rango, comentario de documentación, scip_symbol; índices de salto ngram sobre el nombre. |
code_symbol_names, code_symbol_ids |
RMT, rellenada por code_symbol_names_mv / code_symbol_ids_mv |
Los símbolos reorganizados con otra clave: por nombre corto y por id. |
code_edges |
RMT(version), (org, namespace, tier, to_symbol_id, edge_kind, from_symbol_id, path, line) |
Los llamadores son un rango de claves; proyecciones by_from (llamados) y by_path. |
code_call_sites_unresolved, code_caller_guards |
RMT(version) |
Sitios de llamada rechazados, por nombre del llamado; guardas alrededor de los sitios de llamada de cada llamador. |
code_term_freq, code_doc_stats |
AMT, RMT; rellenadas por code_term_freq_mv, code_doc_stats_mv |
Estadísticas BM25 para la rama léxica. |
code_unit_signal |
SummingMergeTree((positive, negative)) |
Contadores de resultados por unidad a partir de code.outcome. |
code_search_trace, code_search_outcome, code_search_memo |
MT con TTL de 180 días; RMT con TTL de 60 minutos | Trazas y resultados por consulta; una memoria temporal de las respuestas de code.search ya servidas. |
Todas las columnas están en la referencia del esquema generada.
Patrones de consulta
| Op | Ruta | Cómo |
|---|---|---|
code.search |
code/app/search/pipeline.py |
Primero enruta (patrón, ruta, pregunta de historial) y luego ejecuta las ramas bajo el plazo límite (gather.py): léxica (conteo de tokens ponderado por idf), vectorial (un escaneo sin índice vectorial, o una lista corta de gemelos), historial de PR y voto difuso de símbolos. fusion.py fusiona por rango recíproco (k = 60); serve.py pagina dentro del presupuesto de tokens o se abstiene. Una repetición dentro de la ventana de memo es una sola lectura de code_search_memo. |
code.grep |
code/store/index/grep.py |
El índice de 3-gramas reduce los gránulos; position() o match() decide; cada coincidencia se une a su unidad contenedora. mode=presence abarca hasta ocho espacios de nombres de rama. |
code.symbol |
code/app/symbol/ |
Un nombre calificado es una lectura por prefijo de clave de code_symbols; un nombre corto pasa por code_symbol_names; varias definiciones se ordenan por near_paths o por el PR en revisión. |
code.callers, code.impact |
code/store/index/edges.py |
Los llamadores son el rango to_symbol_id de code_edges, con preferencia por las filas del compilador, junto con el conteo de no resueltos. code.impact asigna los fragmentos del diff a símbolos semilla y recorre hacia afuera; un recorrido vacío responde no_indexed_paths, no_seeds_in_hunks o no_static_callers. |
code.outline, code.enclosing |
— | Lecturas por ruta de los tramos de code_symbols y code_chunks. |
Invariantes
- Un espacio de nombres de código es una rama; cada fila
code_*está identificada por(org, namespace). git_headavanza solo después de que se hayan escrito todos los archivos del commit.treesitter.symbol_ides la única función de symbol-id, usada por ambos niveles y por la ruta de lectura.- Los ids de chunk se direccionan por contenido; un chunk sin cambios no se vuelve a generar como embedding.
- Un cambio de código en un módulo marcado (stamped) vuelve a derivar sus etapas para su familia de lenguaje en cada espacio de nombres; los comentarios y docstrings nunca lo hacen.
- Aplicar un delta es idempotente y marca como eliminado (tombstone) lo que el productor dejó de emitir.
- El servidor nunca analiza protobuf de SCIP.
- La cobertura por commit es una comprobación de ascendencia en el mirror, nunca una marca de agua.
- La recuperación filtra
embedding_dim > 0; un chunk stub solo se puede buscar de forma léxica.
Puntos de entrada del código fuente
| Ruta | Qué |
|---|---|
server/code/app/index/ingest_pass.py |
La pasada del nivel rápido. |
server/code/app/index/ingest.py |
ingest_file, las etapas por archivo. |
server/code/app/index/ingest_parse.py, ingest_chunks.py, ingest_edges.py, ingest_resolve.py, ingest_reconcile.py |
parse_for_ingest y _PARSERS, fragmentos, aristas, lecturas de resolución de aristas, escrituras de diferencias por clave. |
server/code/domain/extract/treesitter.py, lang_detect.py, lang_*.py, lane_units.py |
Lenguajes. |
server/code/domain/extract/chunker.py, edges_treesitter.py, call_guards.py; server/code/app/index/dependents.py |
Fragmentos y aristas. |
server/code/domain/extract/extractor_stamp.py |
El sello. |
server/code/app/index/reconcile.py, commit_coverage.py, scip_delta.py; server/code/domain/index/compiler_tiers.py |
Desfase, cobertura, niveles. |
server/code/workers/scip_*.py, scripts/scip_harness/ |
Nivel del compilador. |
server/code/workers/embed_recovery.py, summary.py, graph_stats.py, pr_history.py, backport_gaps.py, coverage_notify.py |
Workers en segundo plano. |
server/code/domain/index/repos.py; server/code/app/index/repo_registry.py, registry.py, retire.py, gitrepo.py |
Entradas, réplicas, espacios de nombres. |
server/code/app/search/, server/code/store/index/ |
Lecturas y escrituras. |