As páginas sem tradução abrem em inglês e são identificadas como inglês.
Esta página é uma tradução automática da página em inglês, que prevalece. Machine-translated from the English page, which is authoritative.
Arquitetura do índice de código
Esta página é a visão interna do índice de código: como os arquivos se transformam em chunks, símbolos e arestas, e como as duas camadas se mantêm atualizadas. O que cada op responde, as linguagens e sua profundidade, e como interpretar as_of estão na visão geral do índice de código e em atualidade dos dados. A operação (clones, backfills, as camadas do compilador) está em operações do índice de código.
Objetivos e não objetivos
| Objetivos | Não objetivos |
|---|---|
| Atualização da camada rápida a cada merge, a partir de um poll de um espelho bare local; sem webhook de entrada. | Indexar uma árvore de trabalho. Alterações não commitadas e não enviadas por push nunca entram no índice. |
| Arestas exatas de chamada, sobrescrita e herança onde existe um indexador baseado em compilador; heurísticas graduadas nos demais casos. | Executar um compilador no processo do servidor. Os produtores de SCIP são executados em subprocessos do processo workers. |
| Ingestão idempotente: bytes inalterados geram as mesmas linhas e não custam nenhum embedding. | Um host de código de uso geral. O índice é um dado de referência somente leitura, identificado por namespace. |
| Toda resposta informa o commit e a camada que leu, e explica por que uma resposta vazia está vazia. | Esconder a defasagem. Uma camada atrasada é reportada. |
| Uma nova linguagem entra sem reindexar as outras. | Mesma profundidade para todas as linguagens (linguagens). |
Um namespace, um branch
Um namespace de código é um branch de um repositório em um commit. Ele tem kind='code' em
loom.namespaces (code/app/index/registry.py, ensure_registered), não guarda
memórias e identifica cada linha code_* por (org, namespace). O Loom mantém um espelho
git bare por repositório, um cache do remoto registrado no ClickHouse: code_ingest clona
um espelho ausente (ou loom code init o faz, com antecedência) e o atualiza com fetch a cada passada.
server/code/app/index/gitrepo.py chama o git por shell; não há árvore de trabalho e nada é escrito
além do fetch. Os branches de um mesmo repositório compartilham o espelho.
Uma leitura de histórico (blame_range, bisect, first_build, a verificação de código de uma lição) em um host
sem o espelho o clona uma vez em segundo plano
(server/code/app/index/mirrors.py, history_dir). Uma leitura que nomeia sua op espera até
10 s pelo clone que iniciou, ou pelo que restar do orçamento de latência da op, o que for
menor; as demais respondem no_git_mirror até que o clone termine. Após o clone, os commits de merge
do ledger que o clone não tem são buscados por sha e fixados: um merge feito em um branch de staging
que o upstream já apagou está no espelho do worker (nunca podado), mas não em um clone
novo. Um espelho presente responde como está; um que não tem o head indexado
busca o branch em segundo plano. Um head que não é o do branch (o head de um PR) não é buscado.
Isso coloca uma cópia completa de cada espelho em cada host de serviço que for consultado, o que é
o objetivo (qualquer host responde a leituras de histórico após uma mudança ou um scale-out) e o custo
(disco por host: o tamanho de um repositório cada). LOOM_CODE_HISTORY_CLONE_ON_READ=false
desativa isso: somente o host do worker clona, e uma leitura de histórico em qualquer outro lugar responde
no_git_mirror.
As entradas de repositório vêm de duas fontes, combinadas:
| Fonte | Lida por | Notas |
|---|---|---|
| Ambiente | code/domain/index/repos.py |
LOOM_CODE_REPOS_JSON, ou as configurações escalares LOOM_CODE_*. |
loom.code_repos |
code/app/index/repo_registry.py |
Linhas de autosserviço, por row_kind (abaixo). O token de um remoto privado é armazenado criptografado e nunca é retornado. |
O row_kind de uma linha de loom.code_repos diz o que ela é:
page: um branch adicionado pela página. Ele mantém fora do seu namespace uma entrada do operador, removida ou não.access: a classificação e a política de entrada de uma entrada do operador.'': uma linha escrita antes da coluna, lida como a linha de acesso do namespace de uma entrada do operador e, em outros casos, como um branch adicionado pela página.
configured_repos() lê um snapshot em processo atualizado na inicialização, a cada passada de ingest
e após uma adição. Até a primeira leitura do snapshot, ele levanta RegistryUnread
(com autosserviço ativo), já que as entradas que um namespace de página ignora ainda não são conhecidas; os
módulos que decidem o acesso leem config_entries(), que lista as entradas anteriores a essa
leitura sem nenhuma legível pela organização (tests/unit/test_repo_snapshot_contract.py). Uma op que
precisa da lista completa responde 503 nessa janela; leituras de memória, busca e
memory.for_file respondem sem links de código. Uma chamada de código sem namespace usa por padrão
LOOM_CODE_NAMESPACE somente quando nenhum membro adicionou esse namespace pela página.
Aposentar uma entrada (code/app/index/retire.py) desativa suas linhas, executa uma saga de exclusão em
cada tabela code_* do namespace e remove o espelho quando nenhuma outra entrada o usa
no host que atendeu a chamada; a varredura de cada um dos outros hosts remove a própria cópia.
Mirrors Git em cada réplica
Todo processo de serviço pode responder a uma leitura de histórico (blame, bisect, citações, overlays de PR, cobertura de commits), então cada host mantém seus próprios mirrors bare (code/app/index/mirrors.py). Um mirror é um cache do seu remote: o ClickHouse nomeia o remote, e qualquer host pode reconstruir o mirror a partir dele.
- Warm-up. Na inicialização, cada processo clona os mirrors das entradas indexadas que lhe faltam,
LOOM_CODE_MIRROR_WARMUP_CONCURRENCYpor vez, cada um após uma espera aleatória de até 30 s, para que N réplicas iniciadas juntas não clonem todas do GitHub ao mesmo tempo. Os clones rodam em segundo plano: a prontidão não espera por eles. - O custo de um disco novo. Um host com
LOOM_CODE_REPOS_ROOTvazio faz um clone bare completo de cada repositório indexado (vários GB para um repositório grande) antes de suas leituras de histórico responderem. O warm-up fica ativado por padrão porque uma nova réplica precisa montar seus caches sem um operador; coloqueLOOM_CODE_REPOS_ROOTem um volume que sobreviva a um rollout para pagar esse custo uma vez por volume, não uma vez por pod. Os clones são completos, não--filter=blob:none: um clone parcial busca cada blob ausente no remote enquanto ogit blameroda, o que transforma uma leitura de histórico em uma leitura de rede e alcançaria o remote fora do sandbox de jobs de repositório. - O portão. Toda leitura de histórico passa por
mirrors.history_dir, que retorna o mirror ou o motivo de não haver um. Enquanto o mirror não está presente, a leitura respondeno_git_mirror: cloning <entry>(ou o motivo pelo qual ele não será clonado aqui) em vez de um erro do git, e inicia o clone se nenhum estiver em andamento.LOOM_GIT_HISTORY=nonedesativa o histórico em um host: essas leituras respondemno_git_history. - O loop do host. Somente o líder pergunta ao remote o que mudou (
ls-remotedos branches extras e dos heads de PR). O que a sua passada buscou está no ClickHouse: o tip do branch de cada entrada (clone_head), os heads dos PRs abertos (code_gh_items.head_sha) e os merges do ledger. A cadaLOOM_CODE_MIRROR_FETCH_INTERVAL_S, cada host lê esses dados e busca, por nome, apenas os branches e heads de PR que seu mirror mantém em outro sha, mais uma página de merges do ledger que lhe faltam; um host que está em dia não faz nenhuma chamada de rede. Branches extras não são seguidos em outros hosts: um clone novo traz todos os branches que o remote tinha, e os merges neles chegam pelo ledger. Um processo por host executa a rodada de cada mirror, e todo fetch em um mirror (o da passada, o do loop do host, o de uma leitura) mantém o.fetch-lockdo mirror; o fetch da passada também conta como a rodada do host no intervalo. O mesmo loop executagit gc --no-prunequando devido e varreLOOM_CODE_REPOS_ROOT: mirrors, árvorescheckout-*e arquivos de lock de mirror que nenhuma entrada ativa nomeia (incluindo entradas restritas) e clones incompletos. Ele não varre nada quando o registro não pode ser lido. - Sandbox. Um host sem o sandbox de jobs de repositório nunca clona nem busca uma entrada adicionada por um viewer com remote de rede, tanto no caminho de leitura quanto no worker (
compiler_tier.unsandboxed_skip). - Merges que o remote perdeu. Um merge do ledger que o remote não serve mais ("not our ref" em duas chamadas, para que uma recusa transitória não conte) é registrado no mirror (
loom-unpinned-merges), nunca mais é solicitado e é contabilizado em/v1/health?include=mirrors(mirrors.unpinned_merges) e emloom doctor. - O líder também clona um mirror ausente em segundo plano, para que um clone longo não retenha as outras entradas da sua passada; uma entrada indexada mantém seu estágio no card Repositories enquanto seu mirror é clonado novamente em um novo host.
- Apagamento. Mirrors e checkouts guardam conteúdo de repositório, não conteúdo de memória: o censo de apagamento não os conta. As cópias de um repositório removido somem com a varredura em cada host.
/v1/health?include=mirrors traz mirrors: quantos dos mirrors deste host estão ready e cloning, e failed e absent contados por motivo. Ele responde sem token, então não nomeia nenhuma entrada. O uso de disco é o tamanho de todos os mirrors em todos os hosts: N réplicas guardam N cópias.
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)]
Camada rápida: code_ingest
server/code/workers/ingest.py faz polling a cada LOOM_CODE_INGEST_INTERVAL_SECONDS;
code.refresh dispara uma passada a partir do CI. Por entrada, cada passada:
- Busca o mirror e percorre os commits de first-parent a partir da marca d'água
git_heademcode_index_stateaté o topo, do mais antigo para o mais novo, em no máximoLOOM_CODE_INGEST_MAX_COMMITS_PER_PASS. - Reindexa exatamente os arquivos alterados de cada commit (
ingest_fileemcode/app/index/ingest.py): parse, chunks, símbolos, arestas, call guards, a linha do arquivo, além de um context pack e de um review brief para o PR mesclado que o commit cita. Em seguida avançagit_head. Uma falha reexecuta a partir do último commit completo. - Percorre com a fração
LOOM_CODE_INGEST_WALK_BUDGET_SHAREque sobra: reparos de reconciliação e re-chunks do extrator (abaixo).
| Limite | Efeito |
|---|---|
LOOM_CODE_INGEST_MAX_PASS_SECONDS |
Duração da passada. |
LOOM_CODE_INGEST_PASS_BUDGET_FRACTION |
Após essa fração, a passada não inicia novas unidades, salva os cursores e retorna partial: true. |
LOOM_CODE_INGEST_SECONDS_PER_FILE |
Prevê o custo de um commit; um commit previsto para estourar só começa se for o primeiro da passada. |
LOOM_CODE_INGEST_SLICE_SHARE |
O máximo da fase de commits que um único commit grande pode ocupar antes de ser fatiado entre passadas. |
LOOM_CODE_INGEST_LANES |
Entradas ingeridas em paralelo (padrão 1, até 8). Os commits de uma mesma entrada continuam sequenciais. |
LOOM_CODE_INGEST_ROUND_FILES |
Arquivos por rodada dentro de um commit; leituras pré-carregadas em duas instruções, escritas em lote. |
As lanes ajudam porque uma lane espera round trips do ClickHouse, não CPU.
Admissão. Um arquivo é recusado antes do parse quando corresponde à denylist
(code/app/index/denylist.py, LOOM_CODE_INGEST_EXCLUDE,
LOOM_CODE_INGEST_IGNORE_FILE), é binário ou excede LOOM_CODE_INGEST_MAX_FILE_BYTES.
Assim, coverage_floor: true em um grep significa todo chunk admitido, não todo byte.
Escolha de um parser
ingest_parse.parse_for_ingest tenta as opções abaixo, em ordem. A ordem mantém novos tipos
de arquivo fora do carimbo do extrator:
treesitter.lang_for_path: o núcleo carimbado (C/C++ com.hpela gramática C++, Python, shell, SQL, doc, config). Depois,ingest_parse._lane_languagereclassifica arquivos CMake e configs TLC.- Manifestos Helm e Kubernetes entre os arquivos de config (
lang_gotemplate,lang_k8s). lang_detect.detect_by_extension(LANG_BY_EXTENSION).- Um shebang e, depois, a detecção de shell por nomes do Linguist e diretivas do ShellCheck
(
lang_detect.detect_shell). - Arquivos host (Dockerfile, Makefile, Jenkinsfile, YAML de CI) com
LOOM_CODE_HOST_ISLANDS(lang_hosts). - Fixtures de saída esperada, um chunk sem embedding por arquivo (
lang_reference). - Qualquer outro texto, dividido em chunks sem símbolos (
lang_text).
O parser vem de ingest_parse._PARSERS. Uma falha desse parse, incluindo uma gramática
ausente ou um parse do tree-sitter além de code_parse_timeout_s ou code_parse_memory_mb
(bounded_parse, um parse por vez), degrada para um arquivo apenas com chunks, com
code_files.index_error definido; code.index_errors o reporta; já uma especificação TLA+
recorre ao seu leitor baseado em regex. Um parse que ultrapassa seus limites em qualquer
outro lugar segue o fallback de quem o chamou e não registra erro.
Os módulos do tree-sitter são importados sob demanda, então um servidor com os workers de
código desligados inicia sem os extras de code.
Blocos (chunks)
server/code/domain/extract/chunker.py corta unidades semânticas, nunca janelas fixas:
| Chunk | Conteúdo |
|---|---|
function |
O corpo de uma função. Um corpo grande demais é dividido em instruções de nível superior, cada parte prefixada com a assinatura. |
class_skeleton |
Uma classe com os corpos dos métodos omitidos. |
file_header |
Comentários e includes iniciais. |
other |
O restante, agrupado. |
Arquivos sem árvore recorrem a janelas de linhas inteiras; lanes sem gramática cortam pelos
spans de seus símbolos (lane_units.span_chunks). Um id de chunk é
uuid5("loom://code/{namespace}/{path}#{scope}@{sha16}"). Ele é endereçado por conteúdo,
então um chunk inalterado mantém seu id e seu hash, e a etapa de embedding o ignora sem
consulta. Chunks idênticos em um mesmo arquivo recebem um sufixo ordinal.
Símbolos e arestas
Um id de símbolo é treesitter.symbol_id(qualified_name, signature): os primeiros 128 bits
do SHA-256 sobre o nome e uma assinatura normalizada (espaços colapsados, valores padrão
removidos, de modo que sobrecargas difiram). A camada rápida, o conversor SCIP e o caminho
de leitura o chamam, então ambas as camadas registram um símbolo compartilhado sob um único
id. Python e shell qualificam nomes pelo caminho do módulo, então as muitas funções main()
de uma árvore de testes permanecem distintas.
As arestas da camada rápida (edges_treesitter.py, tier='treesitter') são resolvidas por
nome e graduadas:
| Confiança | Regra |
|---|---|
| 1.0 | Definição única no mesmo arquivo |
| 0.8 | Método da classe envolvente |
| 0.6 | Correspondência única na tabela de nomes de símbolos de todo o repositório |
| none | Ambígua ou desconhecida: sem aresta; registrada em code_call_sites_unresolved |
Uma aresta errada é pior que uma ausente, então code.callers informa quantos sites sua
contagem deixa de fora. Chamadas de construtor (T x(...), new T, make_unique<T>) são
chamadas a T::T. Módulos de tipo de receptor (cpp_receivers.py, py_receivers.py,
ts_receivers.py, go_receivers.py) vinculam chamadas de membro. Os tipos de aresta são
calls, includes, inherits, overrides, uses_type, fixture_use, reads e writes.
Dependentes. As arestas são resolvidas contra uma tabela de nomes de todo o repositório,
então um commit que adiciona, remove ou altera a assinatura de um símbolo muda as arestas de
arquivos intocados que o mencionam. code/app/index/dependents.py reextrai apenas as arestas
desses arquivos no mesmo commit, até LOOM_CODE_INGEST_DEPENDENTS_MAX_FILES. O excedente
aguarda em code_index_state (dependents_pending) e é escoado pela reconciliação.
Embeddings e tabelas de vetores
code_ingest gera embeddings dos novos chunks na própria passada, com memoização pelo hash
do conteúdo (embed_reuse.py), usando texto limitado (embed_text.py). Com
LOOM_CODE_CONTEXT_DESCRIPTION_ENABLED (ativado por padrão), um chunk recebe uma descrição
de uma linha gerada por LLM, anexada antes do texto do embedding, em regime de melhor
esforço e condicionada a orçamento. Uma falha do provedor deixa um stub com
embedding_dim = 0 que code_embed_recovery preenche, com fallback por texto e
envenenamento após LOOM_CODE_EMBED_MAX_ATTEMPTS. Até que LOOM_CODE_READY_EMBED_COVERAGE
dos chunks de um namespace tenha vetores, code.search responde a partir de suas pernas
lexicais e informa isso.
| Tabela | Preenchida por | Uso |
|---|---|---|
code_summaries |
code_summary (semanal, desativado por padrão) |
Cartões de arquivo e de módulo para code.map, controlados por um hash das entradas, com PageRank de code_graph_stats. |
tabelas do segundo modelo, code_chunks_prefix |
LOOM_CODE_VECTOR_TABLES; loom code vector-twin |
A perna vetorial seleciona candidatos no gêmeo menor e repontua com os vetores servidos (prefix_twin.py). |
code_answers |
code.ask |
Cache de respostas indexado pelo embedding da pergunta; servido apenas se o hash de todo arquivo citado estiver atual. |
Passadas em massa deixam cópias extras por chave até um merge. code/app/index/compaction.py
executa OPTIMIZE … FINAL nas tabelas gêmeas após uma passada em massa. code_chunks só é
compactada por loom code compact --table code_chunks --apply.
Camada do compilador: SCIP
A camada do compilador contém símbolos e arestas com tier='scip'. O servidor nunca faz parsing de
protobuf: um produtor converte a saída do SCIP em um delta JSON versionado
(scripts/scip_harness/scip_to_delta.py) e code/app/index/scip_delta.py
o aplica. Para cada arquivo tocado, a aplicação faz upsert do que o delta emite e marca como removidas (tombstone) as linhas scip
do arquivo que ele não emite mais; um arquivo excluído tem todas as linhas marcadas como removidas. Reaplicar um
delta produz o mesmo conjunto ativo.
| Produtor | Linguagem | Watermark | Workers | Como é executado |
|---|---|---|---|---|
scip-clang |
C++ | scip_commit |
code_scip_full, code_scip_delta, code_scip_apply |
TUs alteradas (e TUs que incluem cabeçalhos alterados, com limite) via run_delta.sh; code_scip_full popula a camada e a reindexa semanalmente. |
scip-typescript |
TypeScript / JavaScript | scip_commit_ts |
code_scip_ts_delta |
Índice do workspace inteiro a cada passada, restrito pelo conversor aos arquivos da janela. |
scip-go |
Go | scip_commit_go |
code_scip_go_delta |
Um build por módulo (run_go_monorepo_delta.sh). |
scip-python |
Python | scip_commit_py |
code_scip_py_delta, code_scip_apply |
Delta por merge (run_python_delta.sh); a primeira execução indexa a árvore. |
code/domain/index/compiler_tiers.py (TIERS) é a tabela única de watermark, rótulo
e workers por produtor; os handlers de status e o painel a leem. Um worker de delta
compara seu watermark com git_head, move o checkout (buscando do espelho local,
não da rede), executa o produtor em um subprocesso e aplica o delta
pelo mesmo caminho que code.scip_ingest usa. Uma passada cobre todos os merges desde o
watermark.
Um produtor externo, como um job de CI, pode enviar um delta em partes com
code.scip_ingest; as partes ficam em staging em code_scip_batches / code_scip_parts e
são aplicadas por code_scip_apply. Toda passada da camada do compilador adquire um arquivo de lock por entrada em
LOOM_CODE_SCIP_LOCK_DIR e um lease do ClickHouse, então uma reindexação completa e um delta nunca
executam ao mesmo tempo na mesma entrada. loom code scip-full reconstrói
a camada C++; loom code scip-delta executa uma passada de delta.
Quando as duas camadas têm a mesma linha, as leituras preferem a linha do compilador, e toda resposta
indica a camada que leu (scip ou treesitter).
O stamp do extrator
Chunks endereçados por conteúdo e ids de símbolo com hash dependem da entrada, não do código que
produziu as linhas, então uma correção no chunker nunca chegaria a uma linha existente.
server/code/domain/extract/extractor_stamp.py fecha essa lacuna. Ele calcula o hash dos tokens de código de
cada módulo extrator (logic_tokens: sem comentários, linhas em branco ou docstrings, e um
import reduzido aos nomes que ele vincula, de modo que mover um módulo entre pacotes não altera nenhum
stamp) mais as versões instaladas das gramáticas incluídas no stamp (STAMPED_GRAMMARS: a biblioteca base, C++,
Python, bash).
O stamp é dividido de duas formas, para que uma mudança reprocesse o mínimo possível:
-
Por estágio (
STAGES:chunk,symbol,edge,guard;STAGE_MODULES). O stamp de um estágio cobre seus módulos e os dos estágios que ele lê (STAGE_INPUTS).Módulo alterado Estágios afetados chunker.pychunkedges_treesitter.pyedge,chunk,guardtreesitter.py,lang_python.pytodos ( symbolalimenta os demais)call_guards.pyguard
- Por família de linguagem (
LANGUAGE_FAMILIES:python,shell,typescript,cpp,other;MODULE_LANGUAGES). Uma mudança apenas em Python corrige os arquivos.pye deixa o C++ em paz. Os módulos de arestas do TypeScript (ts_receivers.py,ts_reexports.py,ts_config.py,ts_workspace.py) afetam apenastypescript. Um módulo com stamp ausente emMODULE_LANGUAGESafeta todas as famílias.
A cada passagem, os stamps em execução são comparados com os de code_index_state. Um estágio alterado é
reprocessado para todos os arquivos dessa família em todos os namespaces indexados, em lotes
ritmados (LOOM_CODE_EXTRACTOR_RECHUNK_PER_PASS, chave LOOM_CODE_EXTRACTOR_RECHUNK_ENABLED).
Um stamp registrado vazio é gravado, nunca usado para agir. Portanto:
- uma mudança de código em um módulo de
EXTRACTOR_MODULESreindexa todos os repositórios nas famílias afetadas, o que leva horas em uma implantação grande; comentários e docstrings podem ser editados livremente; - esses arquivos são excluídos dos formatadores (
pyproject.toml), etests/unit/test_code_extractor_stamp.pymantém a lista de exclusão e o inventário de módulos em sincronia: um módulo emserver/code/domain/extract/que não esteja em nenhum estágio deve ser listado emNON_EXTRACTOR_MODULESno teste, com o motivo; - altere-os somente quando a extração mudar, e espere o reprocessamento após o deploy.
Os módulos de lane ficam fora do stamp. Os parsers de lane (lang_typescript.py,
lang_rust.py, lang_go.py, lane_units.py, …), suas gramáticas e os módulos de seleção de arquivos
(lang_detect.py, denylist.py) não o alteram; os módulos de arestas do TypeScript
acima são a exceção. Uma correção de lane é aplicada com loom code backfill --paths-file
sobre os arquivos dessa linguagem.
Reconciliação
As marcas d'água indicam quais commits foram percorridos, não se cada linha está atualizada.
code/app/index/reconcile.py mede o desvio. Uma linha de code_files carrega blob_sha
e indexed_commit. Um único git ls-tree -r <head> marca um caminho como desatualizado (stale) quando seu blob
difere e como removido (gone) quando ele está ausente. Linhas sem blob recorrem a um
git diff --name-only por commit distinto, até LOOM_CODE_RECONCILE_MAX_COMMITS.
A verificação horária em code_ingest (LOOM_CODE_RECONCILE_ENABLED,
LOOM_CODE_RECONCILE_INTERVAL_SECONDS) reingere até
LOOM_CODE_RECONCILE_HEAL_PER_PASS caminhos desatualizados por meio de ingest_file; apenas o conteúdo novo
é embutido em embeddings. Manualmente: loom code reconcile --heal. O gauge loom.code.stale_files
informa a contagem.
Marcas d'água e cobertura
code_index_state (ReplacingMergeTree(version), com chave (org, namespace, state_key))
guarda git_head, as marcas d'água SCIP por produtor, os carimbos do extrator, os cursores e
dependents_pending. O bloco as_of em cada resposta e
loom.code.tier_lag_seconds{tier} são calculados a partir dessas linhas e do mirror, não a partir do log
de um produtor. A cobertura por commit (code/app/index/commit_coverage.py) é um
git merge-base --is-ancestor por camada no mirror, nunca uma comparação de marcas d'água.
O que os chamadores veem está em frescor.
Histórico de PRs, backports e links de trackers
| Tabela | Escritor | Conteúdo |
|---|---|---|
code_pr_history, code_pr_reviews, code_gh_items |
code_pr_history (GitHub REST, cursor em updated_at) |
PRs mesclados com arquivos, comentários de revisão e issues. Um limite de taxa ou um 5xx deixa o cursor parado. |
code_context_packs, code_review_briefs |
code_ingest no commit de merge, ou sob demanda |
Pacote de contexto e resumo para o revisor, por PR. |
code_backport_gaps |
code_backport_gaps (noturno; requer code_pr_history) |
Para cada PR do trunk com label de backport, uma linha por namespace de release branch: coberto, pendente, não afetado. |
code_test_map, code_symbol_stats, code_unit_risk |
code_graph_stats (semanal), loom code crossref |
Mapa teste↔código-fonte, fan-in de símbolos, risco por unidade. |
code_coverage_files |
code_coverage_import (diário), loom code coverage-import |
Por arquivo-fonte, os intervalos de linhas que uma execução de cobertura por teste executou. |
qa_link_candidates |
tracker_links (diário) |
Principais PRs mesclados por issue recente, ranqueados por BM25F, stack frames no diff e menções de fechamento. |
qa_item_embeddings |
tracker_embed |
Vetores de issues e PRs do tracker na janela de embedding; chaves e fatos de filtro, sem texto. |
code.repo.set_source vincula um repositório a seus trackers, em ordem; o primeiro é o
principal, cujos números são os números de issues e PRs do repositório. Os links são a
linha qa_binding de code_index_state e são lidos por (org, namespace): o nome de um
namespace de código é derivado do repositório e do branch, então duas orgs podem ter o
mesmo nome. O LOOM_TRACKER_CODE_NAMESPACE_BINDINGS_JSON do operador se aplica apenas
aos repositórios do próprio operador (LOOM_CODE_REPOS_JSON ou LOOM_CODE_REPO), nunca a
um repositório de autoatendimento cujo nome corresponda a um glob. Os workers do tracker
leem cada namespace por sua própria fonte, então as linhas de um namespace restrito nunca
caem sob um namespace padrão. O contrato de registros está em
contrato de registros do tracker.
code.repo.add_branch grava a linha qa_branch_of do novo branch, nomeando o repositório
raiz (a fonte, ou a raiz da própria fonte quando a fonte é um branch) quando essa raiz é
um repositório do operador, de modo que o branch de uma raiz de autoatendimento nunca
passe a ler o mapa se o operador configurar depois o nome dessa raiz. Um
branch registrado cuja raiz é um repositório do operador segue os links desse repositório
no momento da leitura, incluindo o glob; uma linha qa_branch_of sem uma entrada de
autoatendimento ao lado não é seguida. Uma fonte que não é um repositório do operador tem
a própria linha qa_binding copiada para o branch, inclusive uma limpa. Uma fonte do
operador é sua própria raiz. As duas linhas são gravadas lendo primeiro as linhas da
fonte e gravando qa_branch_of por último, de modo que uma falha deixa o branch sem
seguir nada.
code.repo.remove esvazia a que das duas linhas tiver um valor antes da limpeza
desanexada do namespace. Registrar um namespace esvazia qualquer linha que um namespace
removido de mesmo nome tenha deixado e remove o nome do snapshot do próprio processo, de
modo que o novo namespace não segue nenhuma delas. Um qa_binding esvaziado é lido como
limpo até que um admin do tracker o vincule. Um namespace que não tinha linha qa_binding
não recebe nenhuma, então o mapa do operador ainda alcança uma entrada do operador
configurada com o mesmo nome. Uma entrada do operador configurada com um nome removido não
recebe essa limpeza: até a limpeza ser executada, ela lê a linha qa_binding do namespace
removido, quando existe, com os links antigos após uma remoção na build N-1 e nenhum após
uma na N. Os outros processos mantêm as linhas que leram por até
LOOM_CODE_REPOS_REFRESH_SECONDS.
Armazenamento
| Tabela | Engine e chave | Notas |
|---|---|---|
code_files |
RMT(version), (org, namespace, path) |
Último parse por caminho: linguagem, blob_sha, indexed_commit, index_error. |
code_chunks |
RMT(version), (org, namespace, embedding_model, path, chunk_id), particionada por (org, namespace) |
Conteúdo, lexemes, vetor. Índices de texto: 3-gram em lower(content), tokens em lexemes. |
code_symbols |
RMT(version), (org, namespace, tier, qualified_name, symbol_id) |
Definições com assinatura, intervalo, comentário de documentação, scip_symbol; índices de salto ngram sobre o nome. |
code_symbol_names, code_symbol_ids |
RMT, preenchidas por code_symbol_names_mv / code_symbol_ids_mv |
Os símbolos reindexados por nome curto e por id. |
code_edges |
RMT(version), (org, namespace, tier, to_symbol_id, edge_kind, from_symbol_id, path, line) |
Os chamadores são um intervalo de chave; projeções by_from (chamados) e by_path. |
code_call_sites_unresolved, code_caller_guards |
RMT(version) |
Pontos de chamada recusados, por nome do chamado; guardas em torno dos pontos de chamada de cada chamador. |
code_term_freq, code_doc_stats |
AMT, RMT; preenchidas por code_term_freq_mv, code_doc_stats_mv |
Estatísticas BM25 para a perna lexical. |
code_unit_signal |
SummingMergeTree((positive, negative)) |
Contadores de resultado por unidade a partir de code.outcome. |
code_search_trace, code_search_outcome, code_search_memo |
MT com TTL de 180 dias; RMT com TTL de 60 minutos | Traces e resultados por consulta; um memo de curta duração das respostas de code.search servidas. |
Todas as colunas estão na referência de schema gerada.
Padrões de consulta
| Op | Caminho | Como |
|---|---|---|
code.search |
code/app/search/pipeline.py |
Primeiro faz o roteamento (padrão, caminho, pergunta de histórico) e depois executa as etapas dentro do prazo (gather.py): lexical (contagem de tokens ponderada por idf), vetorial (uma varredura sem índice vetorial, ou shortlist por twin), histórico de PRs e votação fuzzy de símbolos. fusion.py faz a fusão por rank recíproco (k = 60); serve.py pagina dentro do orçamento de tokens ou se abstém. Uma repetição dentro da janela de memo é uma única leitura de code_search_memo. |
code.grep |
code/store/index/grep.py |
O índice de 3-gramas reduz os granules; position() ou match() decide; cada ocorrência é associada à unidade que a contém. mode=presence abrange até oito namespaces de branch. |
code.symbol |
code/app/symbol/ |
Um nome qualificado é uma leitura por prefixo de chave em code_symbols; um nome curto passa por code_symbol_names; várias definições são ordenadas por near_paths ou pelo PR em revisão. |
code.callers, code.impact |
code/store/index/edges.py |
Os chamadores são o intervalo de to_symbol_id em code_edges, com preferência para as linhas do compilador, junto com a contagem de não resolvidos. code.impact mapeia os hunks do diff para símbolos semente e percorre o grafo para fora; um percurso vazio responde no_indexed_paths, no_seeds_in_hunks ou no_static_callers. |
code.outline, code.enclosing |
— | Leituras por caminho de code_symbols e dos spans de code_chunks. |
Invariantes
- Um namespace de código corresponde a uma branch; toda linha
code_*é identificada pela chave(org, namespace). git_headsó avança depois que todos os arquivos do commit são gravados.treesitter.symbol_idé a única função de symbol-id, usada pelas duas camadas e pelo caminho de leitura.- Os ids de chunk são endereçados por conteúdo; um chunk não alterado não é gerado novamente como embedding.
- Uma alteração de código em um módulo marcado (stamped) rederiva seus estágios para a família da sua linguagem em todos os namespaces; comentários e docstrings nunca provocam isso.
- A aplicação de um delta é idempotente e marca como removido (tombstone) o que o produtor deixou de emitir.
- O servidor nunca faz parsing de protobuf SCIP.
- A cobertura por commit é uma verificação de ancestralidade no mirror, nunca uma marca d'água (watermark).
- A recuperação filtra por
embedding_dim > 0; um chunk stub só pode ser encontrado por busca lexical.
Pontos de entrada no código-fonte
| Caminho | O quê |
|---|---|
server/code/app/index/ingest_pass.py |
A passagem da camada rápida. |
server/code/app/index/ingest.py |
ingest_file, as etapas por arquivo. |
server/code/app/index/ingest_parse.py, ingest_chunks.py, ingest_edges.py, ingest_resolve.py, ingest_reconcile.py |
parse_for_ingest e _PARSERS, chunks, arestas, leituras de resolução de arestas, as escritas por diff de chaves. |
server/code/domain/extract/treesitter.py, lang_detect.py, lang_*.py, lane_units.py |
Linguagens. |
server/code/domain/extract/chunker.py, edges_treesitter.py, call_guards.py; server/code/app/index/dependents.py |
Chunks e arestas. |
server/code/domain/extract/extractor_stamp.py |
O stamp. |
server/code/app/index/reconcile.py, commit_coverage.py, scip_delta.py; server/code/domain/index/compiler_tiers.py |
Desvio, cobertura, camadas. |
server/code/workers/scip_*.py, scripts/scip_harness/ |
Camada do compilador. |
server/code/workers/embed_recovery.py, summary.py, graph_stats.py, pr_history.py, backport_gaps.py, coverage_notify.py |
Workers em segundo plano. |
server/code/domain/index/repos.py; server/code/app/index/repo_registry.py, registry.py, retire.py, gitrepo.py |
Entradas, mirrors, namespaces. |
server/code/app/search/, server/code/store/index/ |
Leituras e escritas. |