Atualização do índice de código
Atualização do índice de código
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.
O índice fica atrás do repositório: ele indexa commits mesclados em uma branch configurada, passada por passada, e cada camada avança sua própria marca d’água. Verifique os metadados de atualização da resposta, quando presentes, e o status da camada relevante antes de confiar no código indexado.
O bloco as_of
As operações que retornam as_of expõem os campos de atualização a seguir. As definições
comuns de code.symbol não incluem esse bloco nem um commit; em vez disso, inspecione
code.index_status e verifique a definição retornada em relação à revisão de código-fonte relevante.
| Campo | Significado |
|---|---|
commit |
o commit da camada rápida para este namespace (git_head), não a revisão de cada camada do compilador |
branch |
a branch que o namespace acompanha |
indexed_at |
quando esse commit foi aplicado |
lag_commits |
commits de primeiro pai entre commit e a ponta buscada do mirror; -1 desconhecido |
stale |
lag_commits > LOOM_CODE_STALE_AFTER_COMMITS (padrão 5), ou a busca do mirror está atrasada |
status |
fresh (na ponta), behind (abaixo do limite de defasagem), stale, unknown (lag -1) |
stale_reason |
mirror_not_fetched quando o lag é contado em relação a um mirror que parou de buscar |
fetched_at |
junto com stale_reason: quando o mirror fez a última busca |
failing_tiers |
presente enquanto uma camada falha na entrada: tier, kind, failing_since, failed_passes, fix e, para uma camada com watermark, lag_commits |
O bloco fica em cache por 30 segundos por namespace; uma passagem que move git_head
o invalida. Ele é fail-open: quando a atualização não pode ser lida, o bloco fica vazio e
a resposta ainda é retornada. Trate um as_of vazio ou ausente como desconhecido.
Os fatos de uma camada com falha podem ficar atrás do head mesmo quando stale é false:
com failing_tiers apontando uma camada do compilador, trate as respostas de nível de compilador (grafos de chamadas exatos,
referências) como possivelmente desatualizadas e leia o código em que você confia.
Verifique a atualização, não apenas o estado do build. Um namespace cujo primeiro build terminou
ainda pode estar vários commits atrás. Quando as_of é retornado, inspecione stale; sem ele,
inspecione o watermark relevante por meio de code.index_status. Quando a atualização estiver stale ou
desconhecida, leia do seu checkout os arquivos que você está prestes a editar.
A idade do próprio espelho
O atraso é contado em relação ao espelho local do Loom, então ele indica 0 enquanto o espelho
deixou de buscar atualizações. Por isso stale também passa a ser verdadeiro quando a busca está atrasada, e as
ops de status informam a idade do espelho:
code.index_status(um namespace) ecode.repos(todas as entradas legíveis) retornamclone_head,clone_fetched_atefetch_overdue(mais antigo queLOOM_CODE_FETCH_STALE_AFTER_SECONDS, padrão 3600). Junto com eles:git_head,fast_tier_lag,scip_lag/scip_py_lag, a listacompiler_tiers,last_refresh_atechunks_total/chunks_embedded/embedding_coverage.- Ambas retornam
tier_health: o último resultado registrado de cada camada (fetch, ingest, as camadas do compilador e a execução completa semanal de C++), com o tipo de erro,failing_since,failed_passese a correção enquanto ela falha. Uma camada Go que deixou de fora módulos cujas dependências ela não consegue buscar neste host aparece comostate: "unavailable"(kinddependency_unavailable,failing_sincequando foi notada pela primeira vez, sem contagem de passes) com a sua correção: não está falhando e não está emas_of.failing_tiers. - As linhas de
code.repostrazemsearchable:embedding_coverageatingiuLOOM_CODE_READY_EMBED_COVERAGE.
compiler_tiers tem um cartão por camada que a entrada executa (producer, tool, label,
commit, lag, workers). code.index_status responde de forma compacta via MCP e sempre que
commit está definido; brief: false retorna a resposta completa.
Um commit está em todas as camadas?
Quem revisa um PR já mesclado precisa que todas as camadas contenham esse merge. code.index_status com
commit=<sha> responde em commit_coverage:
| Campo | Significado |
|---|---|
ready |
verdadeiro quando a camada rápida e toda camada do compilador com watermark alcançaram o commit |
waiting_on |
as camadas que ainda não alcançaram |
in_mirror |
se o mirror contém o commit |
fast, tiers[] |
por camada: covered (nulo quando o mirror não tem o commit) e commits_since |
commits_since |
quanto a camada rápida avançou além do commit |
paths_changed_overlap |
com paths=[…]: quais desses caminhos foram alterados por um merge posterior |
Os caminhos em paths_changed_overlap diferem no índice em relação ao commit; leia-os a partir do
seu checkout.
st = await agent.code.index_status(namespace="code-myrepo", commit=merge_sha, paths=pr_files)
cov = st["commit_coverage"]
if not cov["ready"]:
print("waiting on", cov["waiting_on"])
Aguardando a cobertura sem polling
code.coverage.watch publica um evento na caixa de entrada de tarefas (task inbox) assim que um commit é coberto:
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.coverage.watch" \
-H "Authorization: Bearer $LOOM_API_KEY" -H 'Content-Type: application/json' \
-d '{"org":"<org>","namespace":"code-myrepo","commit":"'"$MERGE_SHA"'","inbox":"<your-inbox>"}'
commité um SHA completo ou uma abreviação que o mirror resolve.inboxé uma caixa de entrada de tarefas (inbox.register). O chamador precisa de viewer no namespace de código e de writer no namespace dono da caixa de entrada.- O worker
code_coverage_notify(ativado por padrão, executado a cadaLOOM_CODE_COVERAGE_NOTIFY_INTERVAL_SECONDS, 60) publica um eventocode.coverage.readycompatch{namespace, commit, tiers: [{producer, label, watermark}]}. Ele chega por/v1/task/watch?inbox=…, portask.updatese pelo webhook assinado da caixa de entrada. - Um commit que já está coberto responde
ready=trueeemitted=truee publica o evento na mesma chamada. - Um evento por (namespace, commit, inbox): seu
task_idé oevent_idda resposta, então uma nova tentativa nunca publica duas vezes. As entregas de um mesmo evento são executadas uma de cada vez, sob um lease sobre esse id; assim, entre duas entregas concorrentes, apenas a que armazenou o evento respondeemitted=true. Umcode.coverage.watchque entrega na mesma chamada e espera mais de 10 s por outra entrega responde 409PRECONDITION_FAILED, e 503 quando o armazenamento de leases (Keeper) não responde; tente novamente em ambos os casos. code.coverage.unwatch(mesmos campos) remove um watch pendente;removed: falsesignifica que não havia nenhum ativo.
O SDK Python tem agent.code.coverage_watch(commit, inbox, namespace=…) e agent.code.coverage_unwatch(...). A caixa de entrada é descrita em tarefas e decisões.
Enviando atualizações a partir do CI
O poller (LOOM_CODE_INGEST_INTERVAL_SECONDS, 120) captura todos os merges. Para indexar um
merge imediatamente, chame code.refresh a partir do job de pós-merge com um token de escrita restrito ao
namespace de código:
curl -fsS -X POST "$LOOM_BASE_URL/v1/code.refresh" \
-H "Authorization: Bearer $LOOM_CI_TOKEN" -H 'Content-Type: application/json' \
-d '{"org":"<org>","namespace":"code-myrepo","expected_head":"'"$GITHUB_SHA"'"}'
- A execução cobre apenas o namespace indicado, que deve ser uma entrada configurada (caso contrário, retorna 404), e indexa a branch configurada até o commit mais recente obtido.
expected_headé apenas registrado em log.wait=truebloqueia até o fim da execução (atéwait_timeout_seconds, padrão 300); a resposta traztriggered,already_running,head_beforeehead_after.- A chamada é feita em regime de melhor esforço; o poller corrige um disparo perdido.
Os operadores acompanham loom.code.tier_lag_seconds{tier}; o runbook para camadas atrasadas está em
operações do índice de código.
Configurações
| Configuração | Padrão | Efeito |
|---|---|---|
LOOM_CODE_STALE_AFTER_COMMITS |
5 | commits de atraso antes de as_of.stale ser true |
LOOM_CODE_FETCH_STALE_AFTER_SECONDS |
3600 | idade do mirror antes de fetch_overdue e stale (0 desativa a verificação) |
LOOM_CODE_INGEST_INTERVAL_SECONDS |
120 | com que frequência code_ingest consulta o mirror |
LOOM_CODE_READY_EMBED_COVERAGE |
0.95 | proporção de embeddings antes de code.search usar sua etapa vetorial |
LOOM_CODE_COVERAGE_NOTIFY_INTERVAL_SECONDS |
60 | com que frequência os monitores de cobertura são verificados |
Limites
- A atualização é por namespace de branch. Uma correção integrada à
mainnão está em um namespace de branch de release até ser integrada nele;code.grep mode=presence namespaces=[…]verifica vários. - Pull requests abertos e a sua árvore de trabalho nunca estão no índice.
- Não há push para avisar que “o índice avançou”;
code.coverage.watchnotifica a cada commit.
Relacionados
- overview.md: como ler uma resposta, solução de problemas
- operations.md: as ops de status
- arquitetura do code index: watermarks, reconciliação, o carimbo do extrator