@alembic/embeddings: o caminho de leitura RAG

Durante muito tempo o motor tinha só a metade da escrita — "indexa mas não recupera". O query.ts declara a missão de fechar o gap logo no header: é "The RAG READ path… The index builder WRITES rows; this module READS them back" (packages/embeddings/src/query.ts:1–6). O contrato entre as metades é um só: a consulta TEM de ser vetorizada pelo MESMO backend (e modelo) com que o índice foi construído, "for scores to be meaningful" (query.ts:170–176) — por default, o backend offline determinístico dos dois lados, então buscar num índice offline é hermético, $0 e reproduzível.

Pense como… um catálogo de biblioteca por impressão digital: cada ficha guarda a digital do texto (não o texto), e para achar algo você tira a digital da PERGUNTA com a mesma máquina e procura as fichas de digital mais parecida. Onde quebra: a digital offline é um fingerprint estável do texto, NÃO um embedding semântico real — "suitable for wiring, caching, and index plumbing", diz o próprio backend (offline-backend.ts:11–13); sinônimos não se atraem. O backend real é injetável pela mesma porta.

buildChunkIndex percorre os ChunkRecords de um pacote e, para cada chunk com texto não-vazio, pede um vetor ao backend injetado e valida a linha { chunk_id, package_path, vector, dim, model } na borda (index-builder.ts:67–106). A linha deliberadamente NÃO carrega timestamp — junto com o backend sem relógio/RNG, isso faz "the same chunk always yield the same row" (index-builder.ts:12–15, 61–65). O backend offline default produz vetores de 16 dimensões (OFFLINE_DIMENSION, offline-backend.ts:27) por um hash polinomial por slot, esmagado para [-1, 1) — cada slot dobra os char codes com a posição e um multiplicador ímpar próprio (offline-backend.ts:15–21, 68–89).

const seen = parseExistingChunkIds(existing.value);  // ids já no arquivo
const fresh: EmbeddingIndexRow[] = [];
for (const row of rows) {
  if (seen.has(row.chunk_id)) continue;             // DEDUPE por chunk_id
  seen.add(row.chunk_id);                            // duplicata no lote também colapsa
  fresh.push(row);
}
if (fresh.length === 0) return ok(0);              // 2ª run: appenda ZERO (converge)

writeChunkIndex appenda as linhas em <data-dir>/embeddings-index/<família>.jsonl — APPEND-ONLY com dedupe por chunk_id lido do arquivo existente, então rodar de novo sobre os mesmos chunks escreve nada e o índice converge (index-builder.ts:123–158). O leitor default resolve para '' em ENOENT — "a missing index is an empty index" (index-builder.ts:184–199). É exatamente o que alembic embed-index <família> faz por baixo.

O kernel puro é queryChunkIndex: só linhas com a MESMA dimensionalidade da consulta competem (índice heterogêneo degrada gracioso, nunca erra — query.ts:77–82, 108–109), vetor de magnitude zero pontua 0 (cosseno indefinido; 0 é o neutro "ortogonal" — query.ts:130–141), e topK/minScore inválidos falham fechado. Em volta dele, searchChunkIndex resolve o arquivo (<dataDir>/embeddings-index/<família>.jsonl, o layout exato que alembic embed-index escreve — query.ts:156–164) e NÃO carrega o índice inteiro: varre linha a linha via openLineStream mantendo um top-K limitado — "memory is O(topK), never O(rows)" — com resultado byte-idêntico ao caminho puro porque a inserção usa o mesmo compareHits e preserva a ordem do stream em empate total (query.ts:196–201, 309–336). Índice ausente? ok([]) — resultado vazio, não erro (query.ts:189–190). E um detalhe de design que liga com a lição 19: a linha do índice não guarda texto — chunk_id + package_path localizam o chunk no pacote, e resolveSnippetTexts lê o chunks.jsonl de cada pacote (uma vez só por pacote) quando o texto é necessário, com fallback à linha-referência determinística (query.ts:38–42; rerank.ts:216–255).

Cosseno puro tem um vício conhecido: os top-K tendem a ser quase-duplicatas — "the same idea, restated" (rerank.ts:7–12). O mmrRerank reordena por Maximal Marginal Relevance, PURO: usa só os vetores que os próprios hits já carregam — sem IO, sem backend, sem clock/RNG. A primeira escolha é SEMPRE o hit mais relevante (para qualquer λ, o líder bate com o top-1 do cosseno); cada escolha seguinte maximiza λ·relevância − (1−λ)·maxSimAosJáEscolhidos (rerank.ts:89–106, 149–167).

Fail-closed nas bordas, como sempre: λ não-finito ou fora de [0, 1] é err; topK não-inteiro/não-positivo é err; entrada vazia é ok([]) (rerank.ts:107–121). E um detalhe de arquitetura fino: os helpers de cosseno são RE-DERIVADOS como funções privadas do módulo — os do query.ts não são exportados de propósito, e rerank.ts nunca o importa (rerank.ts:20–24). Quem consome o reranker é o alembic context-pack --retrieve … --rerank mmr: os hits reordenados viram os relevantSnippets do L3 — e sem --retrieve o pack fica byte-idêntico ao anterior.