CL-2026-04-28-BK-CORE-006 - Project Context Layer cache + mtime invalidation

Status: (V)

Escopo: projeto

Projetos afetados: cerebro-kernel

Aprovacao humana obrigatoria: nao

Revisor IA: Gemini (gemini-3-flash-preview, modo plan, read-only) com auditoria final do Claude orquestrador

Resumo

O hot path do router (callLLM) deixou de instanciar ProjectContextLayer por chamada quando o toggle STUDIO_PROJECT_CONTEXT_ENABLED esta ativo. O layer agora vive em cache module-level, e ingestProject so refaz readFileSync/upsertDocument quando o mtime do arquivo no disco mudou em relacao ao que esta indexado.

Alteracoes

• kernel/project_context_runtime.js: cache module-level projectContextLayerCache, helpers getCachedLayer e resetProjectContextLayerCache, ownsLayer permanente em false quando o cache e usado.
• kernel/project_context.js: ingestProject consulta fs.statSync, compara com metadata.mtime indexada e pula reprocesso quando inalterado, contando em novo array unchanged[]. Opcao { force: true } mantem o caminho antigo sob demanda.
• kernel/tests/unit/project-context-runtime.test.js: bloco getCachedLayer cobrindo cache hit por chave, miss por chaves distintas e reset.
• kernel/tests/unit/project-context.test.js: bloco mtime gating cobrindo arquivo inalterado pulado, fs.utimesSync forcando reprocesso e force: true reprocessando mesmo sem mudanca.
• Backlog/Changelog/Roadmap atualizados.

Comportamento entregue

• Primeira chamada por (dbPath, projectsDir) instancia layer e abre SQLite normalmente.
• Chamadas seguintes reutilizam o handle cacheado; nao ha open/close por LLM call.
• ingestProject mantem-se idempotente, agora com pulo barato quando mtime casa.
• Documentos antigos sem metadata.mtime sao reprocessados ate ganharem o campo, sem migracao especial.
• Telemetria project_context no observability nao mudou de schema; counts continuam representando o estado real (e quase sempre sera 0 ingested + 4 unchanged em regime estavel).

Validacao

Comandos executados:

```bash

node --check kernel/project_context_runtime.js

node --check kernel/project_context.js

cd kernel && npm test -- --runInBand

```

Resultado observado:

• sintaxe OK nos dois arquivos JS;
• Jest do kernel verde com 23 suites e 166 testes (6 novos cobrindo cache do layer e mtime gating).

Observacoes operacionais

• Codex rodou codex exec --sandbox workspace-write e entregou o patch + testes.
• Gemini (gemini-3-flash-preview, modo plan, read-only) revisou o diff e aprovou com gravidade baixa. Apontou como observacao fora de escopo: arquivo removido do disco continua indexado no FTS5 ate reset manual; sera anotado como possivel BK-CORE-009 de garbage collection.
• OpenCode e Kimi nao foram acionados nesta rodada por instabilidade conhecida (provider/schema e timeout 60s, registrados no BK-CORE-004).
• Claude orquestrador auditou diff hunk a hunk contra backup em .backup/BK-CORE-006-... e reconciliou docs.

Proximo passo

Sequencia sugerida: BK-WORKER-001 (hardening dos workers externos) ou BK-OPS-001 (worktree do LegalizaRJ), conforme prioridade humana. BK-CORE-007/008/009 ficam como follow-ups de baixa gravidade.