Skip to content

feat(telemetry): registra QUAIS chunks a busca devolveu (schema v19) - #26

Merged
totobusnello merged 1 commit into
mainfrom
feat/telemetry-per-chunk
Aug 28, 2026
Merged

totobusnello merged 1 commit into
mainfrom
feat/telemetry-per-chunk

Conversation

@totobusnello

Copy link
Copy Markdown
Owner

O quê

search_telemetry ganha top_chunk_ids e top_scores (schema v19). A telemetria
v6 registra a forma de uma busca — quantos resultados, quanto tempo, se o
semantic disparou. Não registra quais chunks voltaram.

Por quê

A primeira pergunta responde "a busca está saudável?". A segunda responde "o que
esta memória já serviu, de fato?" — que é a pergunta sobre a superfície de
recuperação
, o conjunto do corpus que algum dia chega ao agente. Sem os ids não
dá para medir cobertura, concentração, nem quanto do corpus nunca foi exposto.

⚠️ O limite de privacidade é a parte deliberada

Não grava o texto cru da query. O comentário do v6 em db.ts declara que
"não armazenamos texto cru da query por privacidade". A coluna query_text
existe em alguns DBs por reconciliação de drift de schema — e existir não é
autorização para escrever
. query_hash segue sendo a única representação da
query.

O teste B1 lê o INSERT direto do fonte de search.ts e falha se query_text
reaparecer na lista de colunas. Guarda mecânico, não convenção.

Ids de chunk são rowids internos de conteúdo que o operador já possui; a string
da query é o único campo que pode carregar as palavras de um terceiro.

Dois detalhes que não são óbvios

  1. Os dois caminhos de schema falham separado, então são cobertos separado.
    ALTER TABLE só na migração deixa o install limpo sem a coluna; CREATE
    só no caminho novo deixa o DB existente sem ela. A1 cobre um, A2 cobre o outro.
  2. Filtrar antes de mapear. id é opcional em SearchResult. Mapear antes
    de filtrar desalinha as colunas: o undefined some de top_chunk_ids e o
    score correspondente permanece em top_scores — e o par deixa de ser um par.

Como testei

  • 4 testes novos (telemetry-per-chunk.test.ts), 4/4 verdes.
  • Mutação, porque asserção que não morde não é asserção:
    • remover a chamada de migrateToV9só A2 falha (A1 sobrevive pelo
      CREATE, que é exatamente o ponto de separá-los);
    • reintroduzir query_text no INSERTB1 e B2 falham.
  • Suíte completa: 590 passam, 0 falham (node v22, tsc limpo).

A telemetria v6 registra a FORMA de uma busca — quantos resultados, quanto
tempo, se o semantic disparou — e não registra quais chunks voltaram. Isso
responde "a busca está saudável?" e não responde "o que esta memória já
serviu, de fato?", que é a pergunta sobre a superfície de recuperação: o que
o agente realmente recebe.

- `db.ts`: `top_chunk_ids` / `top_scores` no CREATE (install limpo) E como
  `ALTER TABLE` idempotente em `migrateToV9` (DB existente). Os dois caminhos
  falham separado, então são testados separado.
- `search.ts`: serializa os pares depois de filtrar por `typeof id === "number"`
  — `id` é opcional em `SearchResult`, e mapear antes de filtrar desalinha as
  duas colunas (um `undefined` some de uma e o score correspondente fica na
  outra).

⚠️ Limite de privacidade, deliberado: NÃO grava o texto cru da query. O
comentário do v6 declara que "não armazenamos texto cru da query por
privacidade"; `query_text` existe em alguns DBs por reconciliação de drift de
schema, e existir não é autorização para escrever. O teste B1 lê o INSERT do
fonte e falha se a coluna reaparecer.

Testes: 4 novos, e os dois mutantes mordem os alvos certos — remover a chamada
de `migrateToV9` derruba só A2 (A1 sobrevive pelo CREATE, que é o ponto);
reintroduzir `query_text` derruba B1 e B2. Suíte completa 590/590 no node 22.
@totobusnello
totobusnello merged commit dbc5962 into main Aug 28, 2026
1 check passed
@totobusnello
totobusnello deleted the feat/telemetry-per-chunk branch August 28, 2026 07:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant